Imported from leomaro7/skills (.claude/skills/intro-video/SKILL.md). Install upstream with npx skills add leomaro7/skills --skill intro-video. Copyright stays with the author.

Intro Video

紹介動画が失敗するときの原因はほぼ一つに集約される。 スライドに書いた文章を、そのままナレーションで読み上げてしまうことだ。 視聴者は同じ情報を目と耳で二重に処理させられ、どちらも頭に入らないまま数分が過ぎる。

避けるための原則はこうだ。 動画は「読む資料」ではなく「聞く資料」である。 読む資料は視聴者が自分のペースで拾い読みでき、分からなければ戻れる。 動画にはそれが無い。 再生は一方向に進み、視聴者は文字を読みながら同時に話を聞くことはできない。 だから情報を運ぶ主役はナレーションであり、スライドはその場で目に入る手がかり（見出し・キーワード・実物）を置くだけの脇役になる。

この主従関係は、作る順番にそのまま現れる。 台本を先に書き、スライドは台本を支えるために後から作る。 逆にスライドから作ると、スライドに書いた文章を読み上げる台本が自動的に出来上がってしまう。

ワークフロー

1. 着手前に一度だけ確認する

ここで全部聞く。 作り始めてから聞き直さない。 音声エンジンは「台本を外部のサービスに送ってよいか」という判断を含むので、台本を書いたあとに確認すると、答え次第で書き直しになる。 テーマも尺も、後から変わると前の工程がやり直しになる。

素材を読んで埋められるものは埋め、残りを1回のやり取りで確認する。 ただし項目ごとに独立した問いとして出す。

音声とテーマは必ず別の問いにする

一つにまとめてはいけない。 性質がまったく違う判断だから。

• 音声は制約の問題。 「台本を外部に送ってよいか」は組織のルールで決まり、好みではない。 間違えると情報が外に出る事故になる。
• テーマは好みと場の問題。 正解が無く、ユーザーの趣味と相手によって決まる。

これを一つの問いに混ぜると、答えやすいほう（たいてい音声）だけが答えられ、もう片方は既定で流れる。 特にテーマを「トーンから自動で決まる」ことにすると、ユーザーは選んだ自覚のないまま見た目が決まり、作るもの全部が同じ顔になる。 テーマが6つあるのは選んでもらうためで、推測するためではない。

選択肢のある項目（尺・音声・テーマ）は、選択肢を提示する形で、項目ごとに分けて尋ねる。 AskUserQuestion のように複数の問いを1回で出せる仕組みがあればそれを使う（1往復で済み、かつ問いは分かれる）。 無ければ、下のように項目を分けて列挙する。

はじめに3つだけ決めさせてください。

【1】尺
  a. 60〜90秒 — 存在を知らせるだけ。課題と次の一歩に絞る
  b. 2〜3分   — 標準。ひととおり伝わる（おすすめ）
  c. 4〜6分   — 使い方まで手順ごとに解説する

【2】音声：台本を外部（Microsoft）のTTSに送ってよいですか
  a. 送ってよい — neural。最も人間に近い声
  b. 送れない   — local / voicevox。端末内で合成。声は neural に次ぐ
  c. 準備を増やしたくない — os。OS標準。導入不要だが機械的な声

【3】見た目のテーマ
  a. dark      — 暗い地。コードが映える。エンジニア向け
  b. plain     — 白地。どの組織の色でもない無印
  c. corporate — 白地に濃紺、罫線で締める。社外向け・フォーマル
  （ほかに editorial / vivid / mono があります）
  組織やプロダクトのブランド色があれば、あわせて教えてください（例 #0b6bcb）

目的も教えてください。見終わった人に何をしてほしいですか。
（例：「手元の README で一度試す」「次の定例で議題に出す」）

テーマは6つ全部を並べない。 題材と相手から2〜3に絞って出し、残りがあることだけ添える。 選択肢が多すぎると選べなくなる。 迷われたら、同じ内容で2テーマ作って見比べてもらう（apply_theme.py で差し替えて撮り直すだけなので数秒で済む）。

目的は「知ってもらう」では弱い。 「試しにインストールする」のように、視聴後に実際に手を動かせる粒度まで落とす。 ここが決まって初めて、締めのスライドに何を書くかが決まる。

素材が社内資料に見えるときは、こちらから判断して外部に送らない。 音声の問いを飛ばさない。

決めたら brief.json に書き出す

以降のスクリプトはここを読むので、途中で条件がずれない。

{
  "audience": "同じチームの開発者",
  "goal": "手元の README で一度試す",
  "minutes": 2.5,
  "detail": "紹介",
  "external_ok": false,
  "engine": "local",
  "theme": "dark"
}

external_ok が false のまま --engine neural でビルドしようとすると止まる。 約束を散文ではなくファイルで持たせて、後から覆らないようにしてある。

詳細度と尺は連動している

尺を決めると、枚数と台本の分量が機械的に決まる。 先に予算を決めてから書くほうが、書いてから削るより速い。

尺を縮めるときに残すのは「なぜ」と「次の一歩」で、削るのは「どう動くか」の中身。 仕組みの説明が無くても人は試せるが、自分に関係あると思えなければ試さない。

4分を超える場合は、途中離脱が増えることを織り込む。 timeline.json の開始時刻を章立てとして共有し、見たい箇所に飛べるようにする。

音声エンジンの選び方

ブリーフの「外部に送ってよいか」と OS で決まる。

送れないなら neural は落ちる。 残り3つのうち、業務連絡程度の共有なら os で足りる。 最後まで聞いてもらいたいなら macOS / Linux では local、Windows では voicevox を提案する。 Windows で local を勧めないのは、pyopenjtalk のインストールにソースビルドが要るため（references/setup.md）。

読み上げ速度はエンジンで変わる（neural が約5.2文字/秒、ほかは約6.2文字/秒）。 check_narration.py に --brief を渡せば、ここで決めた条件がそのまま使われる。

2. アウトラインを立てる（6〜10枚）

紹介動画には型がある。 素材の構成をそのままなぞらず、この順に組み替える。

尺は2〜3分に収める。 紹介動画は「見るかどうか」を数十秒で判断される。 網羅性より、見終わってもらえることを優先する。 素材が厚いときは、削るのではなく「この動画では扱わない」と割り切って、深い内容は元資料へのポインタに変える。

3. ナレーション台本を書く

narration.json に、スライドと同じ順で書く。

[
  {"id": "01-title", "narration": "..."},
  {"id": "02-problem", "narration": "..."}
]

尺の見積もり：日本語の読み上げは OS 標準の音声で約6.2文字/秒、ニューラル音声で約5.2文字/秒。 1スライドあたり 80〜150文字（15〜30秒）が目安で、全体では 700〜1000文字になる。 150文字を超えるスライドは、聞き手が一枚の絵を見続ける時間が長すぎるので、スライドを分けるか内容を削る。

台本は「書き言葉」ではなく「話し言葉」で書く。 詳しい書き方の原則と、記号・英略語・数字の扱い（OS によって読みが変わる箇所をどう潰すか）は references/narration.md にまとめてある。 台本を書く前に必ず読むこと。

書けたらビルドの前に検査する。 ビルドは数十秒かかり、ニューラル音声では毎回ネットワークに出るので、文字数から分かることは先に潰す。

python scripts/check_narration.py narration.json --brief brief.json

尺の過不足（何文字削る／足すか）、60字を超える一文、文末表現の3連続を指摘する。

台本とスライドがファイルとして分かれているのは、この点で効く。 ナレーション側だけを読み仮名に開いても、スライドの表記は元のまま保てる（スライドには CI/CD と表示し、台本には シーアイ・シーディー と書く）。

4. スライドを作る

assets/template.html をコピーして中身を置き換える。 各 <section class="slide" id="..."> が動画の1カットになり、id が台本の id と一対一で対応する（ずれているとビルド時に止まる）。

テンプレートには5つの土台レイアウトがある。 台本のその一節が何をしているかで選ぶ。

• slide--title / slide--closing — 開始と締め
• .points — 3〜4項目の並列。 項目は文ではなく語で置く
• slide--statement — 一文だけを大きく。 聞き手に刺したい一箇所で使う
• .split — 左に説明、右に実物（コード・設定・出力・スクリーンショット）
• .steps — 手順や流れを横に3〜4個

図を入れたいときは .flow（流れ）・.compare（前後比較）・.bars（比率）・.stack（層）・インライン SVG を使う（references/diagrams.md）。 これらはテーマ変数を参照しているので、テーマを差し替えると図の色も追従する。 画像ファイルを貼るのと違って解像度も落ちない。

なおこのスキルは画像を生成しない。 飾りの写真やイラストは紹介動画では情報を増やさず、ナレーションから注意をそらすだけなので、まず「図で描けないか」を考える。 実物が要るならスクリーンショットを .media で置く。

これに配置のモディファイアを重ねられる。 寄せ（slide--center / slide--right / slide--middle）、分割の比率と向き（split--wide / split--narrow / split--flip）、カードの格子（grid cols-2/3/4）、大きな数字（.metrics）、画像（.media / slide--bleed）。 組み合わせ方と使いどころは references/layouts.md にまとめてある。 新しいレイアウトを起こす前に、まずそこの部品で足りないか見る。

ただし1本の動画で使うレイアウトは3〜4種類まで。 種類が増えるほど画面が落ち着かず、話に集中できなくなる。 部品が多いのは題材ごとに適した3〜4種類が違うからで、1本に全部入れるためではない。

スライドに文字を置くときの基準は一つ、「この文字を、ナレーションと同時に読ませても大丈夫か」。 見出しとキーワードは同時に読めるが、文章は読めない。 だから補足説明はスライドに書かず、台本に回す。

テーマを選ぶ

テーマは1でユーザーに選んでもらってある。 brief.json の theme を当てるだけ。 推測で決めない。 6つは色相だけでなく書体・余白・角の丸み・強調の出し方まで違う。

python scripts/apply_theme.py slides.html --theme dark
python scripts/apply_theme.py slides.html --theme corporate --accent "#0b6bcb"   # ブランド色を当てる

内容を書いたあとでも差し替えられるので、迷ったら2つ作って見比べる。 --accent は組織やプロダクトの色を1色だけ当てるもので、ラベル・箇条書き・強調・区切りがまとめて追従する。 テーマを当てたら撮り直す（--skip-narrate を付ければ音声は作り直さない）。

dark と vivid は地が暗いので、外部画像を取り込むときは --pad-color も合わせる。

色・書体・ロゴ・レイアウトをさらに踏み込んで変える方法は references/design.md にある。

Canva・Keynote・PowerPoint・Figma・Google スライドで作ったスライドも使える。 PNG か JPG で書き出して --frames に渡すと、撮影を飛ばしてその画像を使う。 デザインが既に決まっている場合や、スライドは人が作って音声だけ載せたい場合はこちらのほうが速い。

python scripts/build_video.py --frames ./canva-export --narration narration.json --outdir build

ファイル名を台本の id に合わせておくと確実に対応づく。 連番のままでも、枚数が台本と一致していれば名前順（数字は数値として）で対応づけ、どの画像がどのスライドになったかを表示する。 解像度や比率が混ざっていても、はみ出さないよう縮めて余白を背景色（--pad-color）で埋める。

5. ビルドする

python scripts/build_video.py --brief brief.json \
  --slides slides.html \
  --narration narration.json \
  --outdir build --out intro.mp4

撮影 → 音声合成 → 結合を一度に流す。 成果物は build/ に残る。

• intro.mp4 — 完成品
• build/frames/*.png — スライド画像（そのまま資料に流用できる）
• build/audio/*.wav — スライドごとの音声
• build/timeline.json — 各スライドの開始時刻と台本（章立てや字幕を後から作るときに使う）

台本だけ直したときは --skip-shoot、スライドだけ直したときは --skip-narrate を付けると、変えていない側を作り直さずに済む。 読み上げが速いと感じたら --speed 0.9。

音量は結合時に全体を通して正規化される（既定 -16 LUFS）。 音声合成の出力はそのままだと他の動画より明らかに小さく、視聴者が音量を上げ直すことになるため。

ffmpeg が無いと動かない（macOS: brew install ffmpeg / Windows: winget install Gyan.FFmpeg）。 それ以外の環境要件と詰まったときの対処は references/setup.md にある。

6. 通してから直す

完成した mp4 を最初から通しで見る。 読み直すのではなく、通しで見ることでしか分からない失敗がある。

ビルドの最後に映像と音声の長さが表示される。 ここがずれていると、再生時に「途中で音が切れる」形で表面化する。

• 同じ言い回しの繰り返し — 台本を1スライドずつ書くと「〜できます」が並びやすい。
• 間の詰まり — スライドが切り替わった瞬間に話し始めると、視聴者は絵を認識する前に話を聞くことになる。 --lead で発話前の間を伸ばせる。
• 尺の偏り — timeline.json を見て、1枚だけ極端に長いスライドがあれば分割する。
• 読み間違い — 音声を聞いて、意図と違う読みをしている箇所を台本側でカタカナに開く。
• 声が単調に感じる — --engine の選択を見直す。 OS 標準の音声には自然さの上限があり、台本をどう書いても消せない。 local ならオフラインのまま改善できる。

完成したら、mp4 のパスと総尺、そして直しやすい箇所（台本はここ、スライドはここ）をユーザーに伝える。

出力先

素材のあるディレクトリの隣に、専用のディレクトリを作って一式を置く。 散らかさないことと、後から台本だけ直せることの両方が目的。

<題材名>-video/
├── brief.json         # 着手前に確認した条件
├── slides.html        # スライド（編集する）
├── narration.json     # 台本（編集する）
├── intro.mp4          # 完成品
└── build/             # 中間成果物

よくある失敗

• 素材の構成をそのまま動画にする。 README の章立てと、紹介動画として聞きやすい順番は別物。 必ず 2 の型に組み替える。
• 網羅しようとして長くなる。 5分の完璧な動画より、2分半の見てもらえる動画のほうが価値がある。
• スライドに文章を書く。 補足は台本に回す。 スライドに文章があるかどうかは、作り終えてから PNG を見れば一目で分かる。
• スライドを先に作る。 台本がスライドの朗読になる。 順番を守る。
• 必要な確認を後回しにする。 音声エンジンもテーマも尺も、着手前に一度で聞く。 台本を書いたあとに「外部に送れない」と分かると、エンジンが変わり尺が変わり、書き直しになる。
• 音声とテーマを一つの問いにまとめる。 答えやすいほうだけ答えられ、もう片方が既定で流れる。 1回のやり取りでよいが、問いは分ける。
• テーマを推測で決める。 6つあるのは選んでもらうため。 トーンから導出すると、ユーザーが選んだ自覚のないまま見た目が決まる。
• テーマを選ばずに既定のまま出す。 6つあるのは、題材と相手によって適切な見た目が違うから。 どれも選ばないと、作るもの全部が同じ顔になる。

参照

• references/narration.md — 読み上げ向け日本語の書き方。 台本を書く前に読む
• references/layouts.md — 配置のカタログ。 寄せ・比率・格子・数字・画像の置き方
• references/diagrams.md — 図の描き方。 流れ・比較・比率・層・インライン SVG
• references/design.md — テーマの中身、ブランド色の当て方、ロゴ、外部ツールのスライドを使う
• assets/themes/*.css — 6つのテーマ。 新しいテーマを足すときはここに1ファイル増やす
• references/setup.md — 環境要件、OS ごとの音声、詰まったときの対処
• assets/template.html — スライドテンプレート