teaching-site

ティーチングサイト — メインエントリーポイント

スキーマの権威：すべてのプリミティブフィールド名（unit / concept / prompt / task / material / quiz / faq / illustration）と正式なプロジェクトレイアウトは、_shared/domain-primitives.md に定義されています。いずれかのサブスキルに振り分ける際は、エージェントがまずこのファイルを参照することを想定してください。

ファイル名の規則（英語優先）：生成されるすべてのファイルには英語名を使用します（course-package/、day{n}/outline.md、materials/ など）。ユーザーがチャットで使うトリガーフレーズは中国語のままでも構いませんが、ディスクに書き込む内容はすべて英語にします。全体の対応表は _shared/domain-primitives.md §0 を参照してください。

リファレンス実装：d:/GitHub/ai-workshop/ は本番環境のリファレンス実装です（4日間のワークショップ、4125行の index.html、1728行の course-data.js）。ビジュアルとレンダリングパターンのリファレンスとして使用し、コース固有の内容はコピーしないでください。

これは、インタラクティブなティーチングウェブサイトを制作するためのトップレベルスキルです。白紙の状態からのアウトライン作成から、PDF電子書籍の納品まで、あらゆる段階を網羅する10個の専門サブスキルを調整します。

このスキルとサブスキルの使い分け

• 次の場合は、このスキル（teaching-site）を使用します。

  • ユーザーの依頼が広範な場合（「做一套課程網站」、「我想做工作坊」）。
  • ゼロから始めるため、どこから手を付ければよいかわからない場合。
  • ユーザーが複数の段階を行き来しており、調整が必要な場合。
  • 変更後に成果物間の整合性を確認する必要がある場合。

• 次の場合は、サブスキルを直接使用します。

  • ユーザーが成果物を指定している場合（「做電子書」→ course-ebook-publishing）。
  • パイプライン全体の概要が不要なほど、特定の段階をすでに深く進めている場合。
  • 別のスキルが、特定のサブタスクのためにここへ振り分けている場合。

どちらの方法でも、サブスキルに到達できます。直接トリガーする方法と、このスキルの振り分けを介する方法があります。

制作パイプライン

ティーチングサイトは、5つのコアレイヤーと、その最後にある2つの任意の派生レイヤーで構成されます。

[Stage 1] outline (.md)
    ↓ produces: meta, day list, unit skeleton, learning goals, shared scenario
[Stage 2] content authoring (.md / .csv / .yaml)
    ↓ produces: lecture notes, sample materials, quiz items, optional prompt templates
[Stage 3] SPA conversion (.js + .html)
    ↓ produces: course-data.js (data) + index.html (renderers), local serve setup
[Stage 4] interactions (.js + .css inside index.html)
    ↓ produces: progress persistence, sidebar/scrollspy, theme, RWD, quiz UX
[Stage 5] visual assets (.png / .svg / scraping scripts)
    ↓ produces: illustrations, screenshots, QR codes, maps
    ▼
─── site is now feature-complete ─── (optional derivatives below)
    ▼
[Stage 5b] Corporate Edition branch   ← optional, parallel to ebook
    ↓ produces: corporate-editions/ folder, condensed units, inlined COURSE, asset fallback chain
[Stage 6]  Ebook Publishing            ← optional, ALWAYS after site is stable
    ↓ produces: dist/{name}.pdf + .docx via single composed master.md

通常、ステージ1〜5は順番に進めますが、ユーザーはしばしば前の段階に戻ります（ユニットを追加する場合、アウトラインと course-data.js、さらに関連するビジュアルも更新する必要があります）。こうした参照関係の把握こそ、このスキルの主な付加価値です。

**ステージ5bと6は、完成したサイトを利用する下流工程です。**正式なサイトを読み取りますが、変更は行いません。ステージ1〜5がまだ流動的な間は実行しないでください。手戻りのコストが高くなります。

サブスキルの振り分け表

該当するステージが進行中の場合は、エージェントのスキル有効化機能を使って対応するサブスキルを実行します（Claude Code：Skill ツール、Codex：skill ツール、Antigravity / Gemini CLI：activate_skill）。

ステージ	サブスキル	トリガーフレーズ
1	course-outline-design	「課程を計画」、「課程の概要」、「日数の割り振り」、「学習目標」
2	course-content-authoring	「講義資料を書く」、「素材を補う」、「小テストを作る」、「プロンプトのテンプレート」
3	static-spa-conversion	「ウェブページにする」、「SPAに変換する」、「course-data.js」、「render関数」
4	static-spa-interactions	「進捗チェックを追加する」、「レスポンシブ」、「ダークモード」、「ズーム」、「scrollspy」
5	web-visual-assets	「イラスト」、「ツールのスクリーンショット」、「QR」、「講師カード」、「地図」
5b	course-corporate-edition	「企業向け一括研修」、「短縮版」、「カスタマイズ」、「1日に短縮する」
6	course-ebook-publishing	「電子書籍を作る」、「PDFを生成する」、「受講者に印刷して配る」、「DOCXを納品する」
╳	web-visual-verification	「ウェブページを検証する」、「RWD検証」、「Playwrightテスト」、「スクリーンショットを比較する」
╳	web-content-audit	「コンテンツを棚卸しする」、「アセットを監査する」、「不足している画像を探す」、「3か所の同期を確認する」
╳	teaching-site-design-system	「ビジュアルスタイル」、「デザインシステム」、「カラーパレット」、「フォント」、「ガラスカード」

最後の3つ（╳印）は横断的なスキルであり、特定のステージには属しません。最初の2つ（検証／監査）は、実行時の動作とファイル間の参照関係を確認するための安全策です。3つ目（デザインシステム）は、すべてのステージが参照するビジュアルの基準です。

Stage 1 ゲート（厳格なルール — どのステージにも進む前にお読みください）

どのステージ（2〜6、5b、横断的なスキルを含む）に進む前にも、Stage 1 の成果物がディスク上に存在することを確認してください。

• 概要ファイル（例：overview.md）に、對象／總時數／每日主題 の各項目が見出しだけでなく、内容まで記入されている。
• 少なくとも1つの日ごとのアウトラインファイル（例：day1/outline.md）に、ユニット ID と学習目標が記載されている。

共有シナリオ（shared-scenario.md）は任意です。これは course-outline-design の完了ゲートで判断する後続の項目であり、ここに進むための要件ではありません。

上記2項目のどちらかが欠けている、または仮置きの内容しかない場合： ユーザーが後のステージを明示的に指定していても（「電子書籍を作って」「quiz を書いて」など）、後続ステージには進まないでください。まず course-outline-design に進み、ユーザーに次のように伝えてください。

「完全なコース概要がまだないようです — Stage N に直接進むと、後からアウトラインを変更するたびに複数のファイルを連動して作り直すことになります。まず course-outline-design でアウトラインを確定しましょう。決定にかかる時間は約10分で、その後の数時間に及ぶ手戻りを省けます。」

Stage 1 のオーバーライドポリシー（3項目による例外措置）

ユーザーがゲートをスキップすると明示的に希望した場合（「分かっているので、先に進めてください」「アウトラインは飛ばして、X だけ作ってください」など）、以下の条件に従って進めます。

1. 後続の作業に進む前に、チャットで3項目を貼り付けるよう依頼します。
   • 對象：受講者が誰か＋前提知識を1文で説明
   • 總時數 + 每日時段：例：「2日 × 6時間」
   • 每日主題：Day 1／Day 2／... をそれぞれ1行で記載
2. その3項目をそのまま仮の overview.md に保存し、進む前に `` と記載します。
3. ユーザーが3項目の仮置きも拒否した場合は、厳格な手順に戻ります。オーバーライドを拒否し、course-outline-design に進みます。

この仮ファイルは監査記録です。このサイトを読む今後のセッションで、Stage 1 が迂回されたことをすぐに確認し、経緯を把握できます。

Stage 2 ゲート（厳格なルール — Stage 3 以降に進む前にお読みください）

Stage 1 ゲートを通過した後、Stage 3（static-spa-conversion）、Stage 5b、または Stage 6 に進む前に、Stage 2 の成果物がディスク上に存在することを確認してください。

• overview.md に記載されている各 Day について、それぞれの day{n}/content.md が存在する。
• 各 content.md に、対応する day{n}/outline.md で宣言されたすべてのユニット IDについて、## u-{id} セクションがある。1つだけでは不十分です。
• 各ユニットセクションに実質的な内容がある。次のいずれか1つ以上が必要です。（a）約10行以上の講義原稿、（b）任務 (tasks) リスト、（c）素材需求 の参照。見出しだけのユニットは不合格です。
• 各ユニットセクションに **圖片需求 (illustrations)** があり、ファイル名と簡単な仕様を含む項目が1〜3件列挙されている。下記の Stage 5「画像カバレッジの最低要件」を参照してください。

いずれかの項目を満たさない場合： ユーザーが後のステージを明示的に指定していても、Stage 3 以降には進まないでください。まず course-content-authoring に進み、ユーザーに次のように伝えてください。

「アウトラインはありますが、Day {n} の content.md が{欠けている／中身がない／ユニット u-{id} の内容がありません}。そのままウェブページを作ると、中身の薄い殻になってしまいます — 受講者が目にするのは見出しの一覧だけで、実質的な教材がありません。まず course-content-authoring で各ユニットの講義／タスク／画像要件を補完すれば、後からウェブページ一式を作り直すより何倍も時間を節約できます。」

Stage 2 のオーバーライドポリシー（簡易デモ向けの例外措置）

ユーザーが簡易デモを明示的に希望した場合（「まずは殻だけでいいです」「顧客にレイアウトを見せるデモだけ欲しいです」「コンテンツは飛ばしてください」など）、以下の条件に従って進めます。

1. 何を犠牲にするかをチャットで明確に伝えます。簡易デモにはユニット名だけが含まれ、講義本文はなく、イラストはプレースホルダーの <div> に置き換わり、タスクは空のチェックボックスになります。
2. 対象となる各 day{n}/content.md にヘッダーコメント `` を記載します。ファイルがない場合は仮ファイルとして作成します。
3. course-data.js を生成する際、対象となる各ユニットに __thinDemo: true を設定し、SPA に「本単元尚未填內容」バッジを表示します。デモ版にたまたまアクセスした受講者も、実際のコンテンツではないことを確認できます。

この3つすべてを満たさない限り、先には進まないでください。依頼を拒否し、course-content-authoring に進みます。

ステージ 5 画像カバレッジの最低基準（必須ルール — 「サイトの機能がすべて完成」と宣言する前に適用）

カバー画像と最低限のテキストだけのサイトは骨組みだけのように感じられ、学習者は最初のスクロールで離脱してしまいます。ステージ 1〜5 が完了したと宣言する前（つまり、ステージ 5b／6 への移行が可能になる前）に、次の項目を確認してください。

• course-data.js のすべての単元に、1〜3 個のエントリーを含む illustrations[] 配列がある。（従来の単一の illustration: 'foo.png' フィールドは 1 個として数え、このチェックでは illustrations: [{ name: 'foo.png', kind: 'hero' }] として扱います。）
• 各単元に少なくとも 1 つ、assets/ 配下に存在するファイルを参照するエントリーがある。（ステージ 5 の進行中は、残りが SVG のフォールバック用スタブでもかまいません。）
• 単元に本当に挿絵が不要な場合（まれなケース。例：5 分の事務的な時間枠、クイズのみの単元）は、明示的な免除を記録します：illustrations: [{ kind: 'waived', reason: '...' }]。記載がなければ合格とはなりません。
• assets/illustrations/（またはプロジェクト内の同等のディレクトリ）に、カバーだけでなく単元ごとの画像も含まれている。

未達の場合： web-visual-assets に依頼し、ユーザーに次のように伝えます。

「現在、挿絵のない単元が N 個あります（または、サイト全体でカバー画像しかありません）。学習者はページを開いたときに内容がとても少なく、草稿のように感じるでしょう。電子書籍／企業向け研修パッケージの分岐に進む前に、まず web-visual-assets で一括画像生成を実行することをおすすめします（各単元 1〜3 枚、PNG-first／SVG-fallback を併用）。そうしないと、PDF を印刷したときに大きな余白だらけになります。」

この基準は、ステージ 4（インタラクティブ機能の実装）が完了した後、ステージ 5b または 6 に移行する前に確認します。ステージ 5b／6 には、既存の画像がそのまま引き継がれます。この基準を省略すると、企業向けパンフレットも PDF 電子書籍も空のまま納品されてしまいます。

現在のステージを見分ける方法

ステージ 1 ゲートとステージ 2 ゲートの両方に合格した後、次の兆候を確認して適切な後続ステージを選びます。

• アウトライン .md は存在するが、day{n}/content.md がない、または内容が乏しい → ステージ 2（course-content-authoring）。ステージ 3 へのスキップにはゲートがあります。上記のステージ 2 ゲートを参照してください。
• コンテンツ .md は完成しているが、course-data.js がない → ステージ 3（static-spa-conversion）。
• course-data.js は存在するが、index.html にレンダラーがない／ローカルサーバーで配信できない → ステージ 3。
• SPA は表示されるが、進捗が保存されない／レスポンシブ対応がない／テーマがない → ステージ 4。
• サイトは動作するが、画像の代わりにプレースホルダーの <div> がある／サムネイルが 404 になる／挿絵のない単元がある → ステージ 5（web-visual-assets）。
• サイトの機能はすべて完成しているように見えるが、ステージ 5 の画像カバレッジの最低基準を満たしていない → まずステージ 5 を実施します。5b／6 にはまだ移行しないでください。
• サイトの機能がすべて完成している（すべてのゲートと最低基準に合格済み）うえ、ユーザーが企業向け／社内向け／短縮版に言及している → ステージ 5b。
• サイトの機能がすべて完成している（すべてのゲートと最低基準に合格済み）うえ、ユーザーが印刷用／保存用／共有可能なファイルを求めている → ステージ 6。

判断が曖昧な場合は、短い質問を 1 つしてから移行してください。すべてのステージを一度に実施しようとしないでください。ステージをまたいだ手戻りのコストは大きくなります。

運用原則

1. ステージを飛ばして先に進まないでください。 ステージ 1 のアウトラインが不完全なままステージ 3 の SPA を生成しないでください。構造上の不一致が増えていきます。ユーザーがスキップを希望する場合は、その旨を明確に伝えてください。

2. 必ず上流の参照元までたどって更新してください。 ユーザーが下流の成果物を変更する場合（例：「2 日目に単元 u-6 を追加」）、同じ変更で上流（outline.md）と下流（course-data.js、関連するビジュアル）も更新してください。更新が一部だけのサイトでは、技術的負債がすぐに蓄積します。

3. コース固有の知識はスキルではなく、ユーザーのコンテンツに属します。 サブスキルは、コースのトピック（AI ワークショップ／料理教室／会計研修など、パイプラインは同じ）に依存しないよう意図的に設計されています。サブスキルに特定分野の例がハードコードされているようなら、問題の兆候です。

4. 検証コマンドも成果物の一部です。 ステージ 3 以降に移行する際は、検証方法（npm run serve を実行し、http://localhost:3000 にアクセス）をユーザーに伝えてください。静的サイトを file:// で開くと、（localStorage がブロックされるため）何もエラーを表示せずに動作しないことがよくあります。

参照ファイル（必要に応じて読む）

このエントリーポイントより詳しい情報が必要な場合は、該当する参照資料を読んでください。

• references/consistency-checklists.md — ステージが切り替わるたびに読んでください。各ステージ（ステージ 1、2、3、…、6、5b）の後に確認する、成果物間のチェックリスト全体が記載されています。「X を変更したのに Y の更新を忘れた」という不具合を見つけられます。

• references/scenarios.md — ユーザーの意図が曖昧なときに読んでください。よくあるユーザープロンプトの例を 12 件（「講義資料の .md はもうあります」「顧客から短縮版と PDF を求められた」など）取り上げ、それぞれに対応する正確なサブスキルの呼び出し手順を示しています。

• references/troubleshooting.md — 問題が報告されたときに読んでください。症状（「素材へのリンクが 404」「進捗のチェックマークがずれた」「PDF にページ番号がない」など）から、該当する可能性が最も高いサブスキル、監査、検証の手順を特定できます。

• references/design-rationale.md — スキルのアーキテクチャ自体を説明するとき、または新機能に独自のサブスキルが必要か、既存のサブスキルに組み込むべきかを判断するときに読んでください。このパイプラインがこのような形になっている理由をまとめています。

このスキルが行わないこと

• コード自体は書きません。必ずサブスキルに処理を委ねます。
• CSS フレームワークやビルドツールは選びません。デフォルトではバニラ HTML/JS を前提とします（理由については static-spa-conversion を参照してください）。
• コースのテーマ、対象者、教育方法は決めません。これらはユーザーの領域です。