1仕組みと動作原理
解消すべき根本原因は「シーン思考」にある：数秒ごとに新しいグラフィックへ切り替えると視聴者はその都度理解をリセットされ、失敗のフィードバックは具体的な欠陥ではなく「分かりにくい／詰め込みすぎ」といった曖昧な不満として現れる。
.claude/skills/video-storytelling/SKILL.md
The failure this replaces is scene-thinking. … rather than as a specific defect.
ここでの狙い：「AIっぽい／分かりにくい」という問題を単一画像の美観ではなく構造的判断に帰着させ、後続する幾何学ルールおよび規律ルールの必要性を導き出す。
1つの永続的な世界：動画全体で同一空間を保ち決してリセットしない。配置済み要素の再描画・移動・ラベル変更を禁じ、空間文法は構築前に確定して全編で一貫させる。
.claude/skills/video-storytelling/SKILL.md
### One persistent world … An element, once drawn, is never redrawn, moved, or relabelled.
ここでの狙い：世界をリセットしないことは以降の仕組み（カメラの移動先確保、スポットライトの成立、オープンループの維持）の前提となる。リファレンス実装では「左右＝成果への進行」「上＝人間かつ唯一の暖色」「下＝システムログ」とし、意味的例外は1度のみ許可（reopen rateの逆再生）。
カメラワークこそが編集：新しいグラフィックへのカットは視聴者の空間把握を奪うが、静止空間内のカメラ移動は認知的負荷を生じさせない。World／Region／Detailの3段階の高さと隣接移動ルールを定義する。
.claude/skills/video-storytelling/SKILL.md
### The camera is the edit … Moving through a space that stays put costs them nothing.
ここでの狙い：カメラワークを情報構造へと昇格させる。手戻りから得られた実践知をルール化（構図は拡大率ではなくワールド座標ウィンドウで記述、同一用途には同一ウィンドウを再利用、オーバーレイは完全不透明にしてからカメラを移動、ラベル余白は端から≥60px確保、連続する2つの動きは1つのジェスチャーに統合）。
注意力はスポットライト：常に1つの要素のみを完全に点灯させ、描画済みの他要素は静穏かつ可読な状態を維持する。視覚的階層は全体を暗くするのではなく「明／静」のコントラスト比によって生み出す。
.claude/skills/video-storytelling/SKILL.md
**Exactly one element at full brightness at any moment. Everything else already drawn stays quiet but legible.**
ここでの狙い：状態と目標輝度（active 200–235 / context 120–150 / spent 85–105、ラベルは常に90以上）を規定し、ナレーションの拍ごとにlit()関数で一元制御。リファレンス実装の初期版では最大輝度が101/255で判読不能だったため、さらに暗くするのではなくインク輝度を上げることで修正した。
空間的なオープンループ：「後で戻ります」と言葉で済ませず、世界の中に未完成の構造物を視覚的に残す。スクリプトの構造に応じて適切な幾何トポロジー（並列項目／深層フロー／階層／対比／ニュース／チュートリアル）を選択する。
.claude/skills/video-storytelling/SKILL.md
Never say "we'll come back to this." Leave something visibly incomplete in the world and return to it.
ここでの狙い：サスペンスを幾何学化し、4段階のメカニズムを規定（フックでの配置、各セクション境界での再提示、視覚的な進行状況、冒頭の全体図での回収）。カウンターには単なる数値だけでなく1〜2語の名前を付与する。
構成要素の規律：読み上げられないものは描画しない。すべての形状はラベル付き要素、ラベル間の接続線、進行中の主体、環境背景のいずれかとし、1セクションあたりの画面上テキスト量は約20語に抑える。
.claude/skills/video-storytelling/SKILL.md
### If it doesn't get a word, it doesn't get drawn … Nothing else.
ここでの狙い：「詰め込みすぎ」の本質を、無意味な形状と意味のある形状が同じ線幅・配色で描かれ、視聴者が無用な解読を強いられる状態と定義。要素予算の制約と「推奨案の上に反例ビジュアルを重ねない」ルールを適用。
グローバルトークンセットによる厳密な制約：線幅 1.5/2.5/4/7、フォントサイズ 22/30/42/60/84、角丸 10/22/40（超楕円 n=2 固定）、5色5意味の装飾ゼロ構成とし、token linterで違反時にビルドを失敗させる。
.claude/skills/video-storytelling/SKILL.md
Full detail in `reference/design-system.md`. … Gate it with a token linter that fails the build.
ここでの狙い：初期版で見られた「局所的には正しいが全体で統一されていない」（線幅18種、フォント9種、差がわずか0.2など）状態の解消。design-system.mdでトークン規則を「the single most important rule」と定め、qa-tokens.mjsで違反を即座に検出。
エンジニアリング障害を教訓化したビルド契約：セクションごとに1つの生成スクリプト、共有モジュールの並行修正禁止、アセンブリ前のSVG defsの名前空間分離、レンダリング時の--workers 1強制。
.claude/skills/video-storytelling/SKILL.md
**Namespace the SVG defs before assembly.** … Cost in the reference build: 35 seconds of empty screen with every gate green. … `--workers 1` on render. Parallel workers make the video layer paint black.
ここでの狙い：手戻り体験をチェック項目へ昇華。defsの名前空間未分離により統合後に画面の大半が空白化（検証ゲートは通過）、並行ワーカーによる画面暗転、ブレス挿入のハードカットによる音声減衰の途切れ（どもりとして知覚）を防ぐ。
検証ゲートの完備と「目視確認の不可欠性」：動きの滑らかさは連続フレーム上で検証し、すべてのゲートは意図的にエラーを起こす対照実験で有効性を確認しなければならない。
.claude/skills/video-storytelling/SKILL.md
**Gates do not replace looking**, and gates that have never failed are not gates. … Motion smoothness is verified on contiguous frames, never on beat frames. … Validate every gate against a control … A seam gate that reports zero on a broken build is worse than no gate.
ここでの狙い：具体的な欠陥パターン（隣接タイルでの急変後に複数フレーム静止＝前寄りのイージング／デッドストップ、1つの動作停止後に別の動作開始＝1つのジェスチャーに統合すべき、単一フレームの乱れ＝ポップ）を提示。リファレンス実装のイントロでも、この種のグリッチがゲートをすり抜けてクライアントの初回視聴で指摘された事例を明記。
文字起こし層ではなく音響層まで踏み込んだ音声監査：トラック全体の無音区間スキャン、1ms解像度のエンベロープ検証、完成動画に対するASR再実行と想定テキストの照合。
.claude/skills/video-storytelling/SKILL.md
**Audit audio at the acoustic level, not the transcript level.** … truncation cliffs and dead holes, not doubled words.
ここでの狙い：文字起こし層のスキャンでは編集起因のノイズを構造的に検出できない（レポート上はクリーンでも実際には途切れが聞こえる）問題を指摘。正しいブレス挿入手順（ルームトーン＋40msの等電力クロスフェード、ハードカット厳禁）を明記。
2コア機能
01長尺動画のビジュアルレイヤー設計手法：永続的世界 ＋ 空間文法 ＋ 3段階カメラ ＋ スポットライト規則 ＋ 空間的オープンループ
02スクリプト構造に応じたオープンループ幾何の選定（並列項目／深層フロー／階層／対比／ニュース／チュートリアル）と再利用可能な実例（wall of slots）
03再利用可能な幾何モジュール：各セクションビルダーで共通の座標インターフェースを保つスロット素材・ライティング定義・超楕円パス生成
04トークン化されたデザインシステム（線幅／文字サイズ／角丸／5色5意味）と違反時にビルドを落とすlinter要件
05生成スクリプトのエンジニアリング規律：セクションごとのbuild_<id>.pyによるHTML単独出力、共有モジュールの並行編集禁止、defsの名前空間分離、--workers 1でのレンダリング
06タイミング規律：語頭への配置同期（0.15〜0.25秒先行）、1.5秒以上の静止画面監査、ルームトーンと40ms等電力クロスフェードによるブレス挿入
07検証ゲート群とフィルムストリップ確認：qa-tokens / no-crossfade / legibility / seamjump / deadframe / presence / integrate ＋ 各トランジションの連続フレーム確認
08隣接スキルとの境界画定：hyperframes-video-beats（話者上のオーバーレイカードを担当）とは異なり、本スキルは動画が「何について扱っているか」の世界そのものを設計
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | FFmpeg（转场窗口连续帧条带抽取，用于读运动缺陷） |
| cli | Node 门禁脚本族（使用者项目内生成的 qa-*.mjs / integrate.mjs，非随包分发）与 HyperFrames CLI |
| package | Python 几何/槽位模块（随包分发，供项目 section builder 导入） |
| package | 兄弟资源：仓库根 docs/STORYTELLING-WORKBOOK.md（中性练习表）与本 skill 的 reference/design-system.md |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトおよびコマンドの実行: （本スキルディレクトリ自体には実行可能なCLIエントリポイントは含まれず、2つの.pyファイルは利用者のプロジェクト生成スクリプトからimportされる幾何計算モジュール）
- 本地工作目录: ファイル読み書きおよび成果物出力: プロジェクト内の compositions/<id>.html（scripts/build_<id>.py により生成。生成スクリプトのみを修正し成果物の直接編集は禁止）
監査ノート： 本スキルのディレクトリ構成は SKILL.md ＋ reference/（デザインシステムmd 1件、README.md と2つの .py を含むパターンディレクトリ）のみで完結しています。2つのPythonファイルは純粋な幾何数学モジュールであり、wall.py はスロット／素材／defs定義の定数文字列を保持し、geom.py は数学計算とSVGパス構築のみを行います。全ディレクトリ内の grep（*.md/*.py）結果において、http、requests/urllib、os.environ、subprocess 等の記述は一切なく、外部ネットワーク通信、認証情報の読み取り、サブプロセスの起動はいずれも行われません。SKILL.md が指示する操作はすべてローカル環境でのビルドおよび検証作業（build_<id>.py および compositions/*.html の生成、レンダリング、プロジェクト内 qa-*.mjs ゲートの実行、ffmpeg によるフレーム抽出、npx hyperframes lint の実行）に限定されます。留意すべき事項はセキュリティ脅威ではなく運用の制約事項です。具体的には、大量のディスク書き込み（スクリプトに数百件のタイムライン数値が埋め込まれ、タイミング変更時は手修正ではなくASTレベルのシフトが必要）や、ドキュメントに明記されたレンダリング制約 --workers 1（並行ワーカーによる画面暗転の防止）が該当します。
5二重目の独立検証
- [ok] 两个随包 .py 是否真的无网络/无 env/无子进程（蓝档关键） — wall.py 仅 import os, sys 用于路径常量与 DEFS 字符串（os 未用于 environ/exec）；geom.py 仅 import math。全目录 grep 无 requests/urllib/socket/http/os.environ/subprocess/eval。结论：几何模块，无执行面。
- [discrepancy] SKILL.md 的门禁脚本是否真属本 skill（避免把项目内产物算作 skill 资产） — ［判定：口径澄清，非缺陷］SKILL.md 的命令写作 node scripts/qa-tokens.mjs、node scripts/build_<id>.py、node scripts/integrate.mjs——这些是使用者项目里生成的脚本，pin 仓库的 skill 目录内不存在（该目录仅 5 个文件）。本报告因此在 internal_assets 只列随包文件，并在 external_deps 标注门禁脚本属项目内生成物。
- [unlocatable] 参考实现的具体数字与事故能否在源码内定位 — SKILL.md 引用的大量参考构建细节（最亮像素 101/255、35 秒空屏、输入口 glitch、被听成 stutters 的 20-40ms 接缝、speaker 在屏约 40%）来自作者对一段私有参考构建的返工记录；pin 仓库内没有该构建的渲染/日志/qa 输出，故这些数字只作「文档声明」记录，不在结论中当已核事实。方法本身（规则名与门禁名）可在 SKILL.md 内逐条定位。
- [ok] 「门禁不能替代人眼」是否只是修辞（会不会把 qa 脚本当通过依据） — SKILL.md 明写 'Gates do not replace looking, and gates that have never failed are not gates.'，并要求每条门用已知会触发的 control 验证、在装配体而非 section 原型上验证、可读性必须看 960x540 降采样、运动必须读连续帧条带。规则自洽且可执行。
- [ok] 音频纪律是否与「剪辑不碰词」原则冲突 — SKILL.md 要求在句界插入 4–8 帧房间音（words never touched）、用 40ms 等功率交叉淡入接进尾音衰减、且插入式改动对转写是确定性位移（无需重转写）——与语速/词不被裁切的原则一致，属对反例（硬接造成 cliff）的显式修正。
6結論
最適な用途： スクリプトに基づく長尺の解説・トーク動画（ニュース解説、特定テーマの深掘り、比較、チュートリアル、リスト動画など）を自作スクリプトで生成するクリエイターに最適：10分規模の動画で視聴者の空間把握を維持したい、流用可能な空間オープンループやトークンシステムを求めている、「自動ゲート＋目視確認」の二重検証を受け入れられるケース。また、「なぜ自分の動画はAIっぽくなってしまうのか」を解明する診断ハンドブックとしても有用。
不向きな用途： 非推奨：① トーキングヘッド動画への簡易なオーバーレイカード付与のみを求める場合（hyperframes-video-beatsを推奨）；② ショート動画や縦型のハイテンポなカット編集（本スキルは長尺かつ永続的な世界向け）；③ スクリプトやゲート検証の構築を行わず、テンプレートのみを即座に使いたい場合；④ 人手による目視・聴覚確認を行えない完全自動化パイプライン（本手法はゲート通過のみでの合格判定を明確に拒否）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload video-storytelling.tar.gz
sha256:
Option B · Copy Guide for Agentaf02bf58b5fef932…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 0d30152a82.