ナレーション付きデータレッスン
リファレンス例（「私たちが誰と一日を過ごすか、年齢別」）のようなレッスンを作成します。ライブチャート上で実行されるナレーション付き動画と、学習者がデータを操作できるExploreタブを備えています。1レッスン = index.html、lesson.json、data.json、video.json（ストーリーボード）、ナレーション音声、およびオプションのBGMを含む1つのフォルダです。
最初に読むもの: references/design-rules.md（承認済みの見た目、動作、強調ルール。正確に従うこと）およびreferences/user-guidance.md（ユーザーとの連携方法）。
以下のパスは、このスキルのフォルダ（${CLAUDE_SKILL_DIR}）からの相対パスです。
誰と作業するか
ユーザーは技術者ではないと想定してください。平易な言葉で、一度に一つのステップを説明し、何か操作が必要なとき（ファイルのダウンロード、ElevenLabsへのサインイン、スクリプトの承認など）は、正確に何をクリックすべきかを伝えてください。コードやJSONの編集をユーザーに依頼しないでください。references/user-guidance.mdのウォークスルーを使用してください。
ワークフロー（チェックポイントと自己チェック付き）
すべてのステップの最後に自己チェックを実行してください。FAILのまま次のステップに進まないでください。
1. データを取得する
- リンク、ファイル、またはPDFを受け付けます。リンクがブロックされている場合（自動ダウンロードをブロックするサイトが多い）、ユーザーにブラウザでダウンロードし、ファイルを共有するように案内します。
- プロファイリング:
python3 scripts/profile_data.py <file-or-url>
2. データは適合するか？（常にユーザーに伝える）
プロファイラーの判定とreferences/chart-chooser.mdを読み、平易な言葉でユーザーに伝えます。
- 適合: 「これは___として機能します。なぜなら___だからです。」それが答える学習質問を挙げます。
- 部分適合: 機能する点、欠けている点、およびトレードオフを説明します。
- 不適合: 明確にその旨を伝え、理由を説明し、どのようなデータが機能するかを説明します。無理に適合させようとしないでください。
✋ チェックポイント1: チャートタイプとストーリーの角度
チャートタイプ、主要な学習質問、および4〜6のストーリービート（ナレーターが指摘する内容。それぞれ計算する数値に関連付ける）を提案します。ユーザーの承認を待ちます。
3. データを整形する
- レッスンフォルダを開始:
python3 scripts/new_lesson.py --chart <type> --out <folder> - ソースをチャートの形式（references/data-formats.md）で
data.jsonに変換する小さく、再実行可能なスクリプトを（レッスンフォルダ内に）作成します。そしてfacts.jsonも作成します。これはナレーターが話すすべての数値を、ソースデータから計算し、どのように話されるかを記述したものです。 - 自己チェック:
python3 scripts/check_lesson.py <folder>を実行。さらに、手作業でソースに対して2〜3の値をスポットチェックします（生のファイルを開いて見つけます）。確認した内容を報告します。
4. ストーリーを書く
video.json（シーン、ビート、キュー）を、references/storyboard.mdおよびdesign-rules §1のストーリーアーク（イントロフック → チャートの読み方 → ストーリービート → サマリー → リフレクション → 「あなたの番」）に従って作成します。- ナレーションスクリプトをElevenLabsスタイル（references/narration.md）で
narration/script.txtに作成します。すべての主張はfacts.jsonと一致していなければなりません。誇張を避けてください（design-rules §8）。 lesson.jsonを記入: タイトル、キッカー、キーラベル、グループの説明、メモ、ソース。
✋ チェックポイント2: スクリプトの承認
スクリプトをプレーンテキストで表示します。ユーザーが質問した場合はオプションを提供します。ユーザーが承認していない変更は適用しないでください。
5. プレビュー（録音前）
- サイレントプレビュー:
python3 scripts/estimate_timing.py <folder>/video.json --out <folder>/narration/narration.words.json、次にpython3 scripts/time_storyboard.py <folder>/video.json <folder>/narration/narration.words.jsonを実行。 - サーバーを起動して開く:
python3 scripts/devserver.py 8123（レッスンフォルダの上のフォルダから実行）、その後http://localhost:8123/<lesson>/にアクセス。 - 自己チェック（ブラウザ）: references/self-checks.mdに従う: すべてのビートでスクリーンショットを撮り、要素の重なりがないこと、コンソールエラーがないこと、すべての名前付き要素がその単語でハイライトされていることを確認。
6. ナレーションと音楽（ユーザーのElevenLabsアカウントが必要）
- ユーザーにサインインを案内します（user-guidance.md → ElevenLabs）。設定: 音声 Quentin – Narrator and Educator、Eleven v4、Stability ≈ 80%、English。スクリプト全体を一発撮りで。
narration/narration.mp3として保存。 - ElevenLabsがない場合? 無料のプレースホルダーを提供:
python3 scripts/placeholder_voice.py <folder>（Mac）。 - 単語のタイミングを調整:
python3 scripts/align_narration.py <folder>/narration/narration.mp3 --out <folder>/narration/narration.words.json、その後time_storyboard.pyを再度実行。単語の一致率が99%以上になることを目指します。 - 音楽（オプション、ElevenLabs Music、インストゥルメンタル、落ち着いた雰囲気、約2分）:
prep_music.pyで準備。動画がトラックより長い場合は、find_loop.py+extend_music.pyで拡張します（ナレーションの下でトラックが終了したりループしたりしないようにします）。 - 自己チェック:
check_lesson.py（音声の長さ、事実） + ブラウザでの完全な再生確認。
✋ チェックポイント3: 一緒にレビュー
完成したレッスンをユーザーと一緒に見て回ります: 何に注目すべきか、Exploreを試す方法を説明します。ユーザーが依頼した変更を行い、変更ごとに自己チェックを再実行します。
7. 公開（オプション）
GitHub Pagesまたは任意の静的ホスト（user-guidance.md → Publishing）への公開手順を案内します。レッスンフォルダは自己完結型です。
自己チェックのルール（常に）
- ステップ3、4、5、6の後、およびすべての修正後に
scripts/check_lesson.pyを実行します。 - 視覚的な変更後はブラウザで確認: ナレーションのタイミングでスクリーンショットを撮り、ストーリーボードと照合します。確認した内容を報告します。
- ナレーションに出てくるすべての数値をソースデータから再計算します。記憶から数値を入力しないでください。
- 何かが失敗した場合、修正して再確認してから、ユーザーに完了したと伝えます。
リファレンスファイル
| ファイル | 使用目的 |
|---|---|
| references/design-rules.md | 見た目、動き、強調、ナレーション、同期、音楽、データの正確性 |
| references/chart-chooser.md | どの質問にどのチャートを使うか、適合条件 |
| references/data-formats.md | 4つのdata.jsonフォーマット |
| references/storyboard.md | video.json: シーン、ビート、チャートタイプごとのキュー、facts.json |
| references/narration.md | スクリプトスタイル、ElevenLabs設定、タイミング、音楽 |
| references/self-checks.md | 各ステップで確認すべき内容 |
| references/user-guidance.md | ユーザー向けの平易な言葉によるウォークスルー |
| references/chart-interface.md | 新しいチャートタイプの追加 |