Schema authority: all primitive field names (unit / concept / prompt / task / material / quiz / faq / illustration) and the canonical project layout come from

_shared/domain-primitives.md

. When dispatching to any sub-skill, expect the agent to consult that file first.

Filename convention (English-first): all generated files use English names (

course-package/

,

day{n}/outline.md

,

materials/

, etc.). Trigger phrases users say in chat may stay Chinese, but anything written to disk is English. See

_shared/domain-primitives.md

§0 for the full mapping.

Reference implementation:

d:/GitHub/ai-workshop/

is the production reference (4-day workshop, 4125-line index.html, 1728-line course-data.js). Use it as visual + render-pattern reference; do not copy course-specific content from it.

• Use this skill (

  teaching-site

  ) when:
  • The user's request is broad ("做一套課程網站", "我想做工作坊").
  • You're starting from scratch and don't know where to begin.
  • The user is jumping between stages and needs orchestration.
  • You need to check cross-artifact consistency after a change.
• Use a sub-skill directly when:
  • The user names the artifact ("做電子書" →

    course-ebook-publishing

    ).
  • You're already deep into one stage and don't need pipeline overview.
  • Another skill is dispatching here for a focused subtask.

• An overview file (e.g.

  overview.md

  ) with populated

  對象

  /

  總時數

  /

  每日主題

  fields — not just a heading.
• At least one per-day outline file (e.g.

  day1/outline.md

  ) listing unit IDs and learning goals.

Shared scenario (

shared-scenario.md

) is optional — it's a downstream decision handled by

course-outline-design

's Completion Gate, not an entry requirement here.

course-outline-design

「我看到還沒有完整的課程綱要 — 直接跳到 Stage N 會讓後面每改一次 outline 就連動多個檔案重做。先用

course-outline-design

把 outline 鎖定，大概 10 分鐘決策，省下後續數小時 rework。」

1. Ask them to paste 3 bullets in chat before any downstream action:
   • 對象：一句話描述學員是誰 + 先備知識
   • 總時數 + 每日時段：例如「2 天 × 6 小時」
   • 每日主題：Day 1 / Day 2 / ... 各一行
2. Save those 3 bullets verbatim into a stub

   overview.md

   (mark it

   <!-- stub created via Stage 1 Gate override on YYYY-MM-DD -->

   ) before dispatching to the requested stage.
3. If the user refuses even the 3-bullet stub, fall back to the strict path — refuse the override and dispatch to

   course-outline-design

   .

static-spa-conversion

• Each

  day{n}/content.md

  exists (one per Day listed in

  overview.md

  ).
• Each

  content.md

  contains a

  ## u-{id}

  section for every unit ID declared in the matching

  day{n}/outline.md

  — not just one.
• Each unit section has substance: at least one of (a) lecture script ≥ ~10 lines, (b)

  任務 (tasks)

  list, (c)

  素材需求

  references. Heading-only units fail.
• Each unit section declares

  **圖片需求 (illustrations)**

  listing 1–3 entries with filename + brief spec — see Stage 5 Image Coverage Floor below.

course-content-authoring

「outline 在，但 Day {n} 的

content.md

{缺/空殼/單元 u-{id} 沒寫}。直接做網頁會生出薄薄的殼 — 學員看到的只是標題清單，沒有實質教學內容。先用

course-content-authoring

把每個單元的 lecture / tasks / 圖片需求補完，比之後重做整套網頁省好幾倍時間。」

1. State explicitly in chat what they're trading away: thin demo will have unit titles only, no lecture body, placeholder

   <div>

   instead of illustrations, tasks as empty checkboxes.
2. Mark every affected

   day{n}/content.md

   (create as stub if missing) with header comment

   <!-- thin-demo stub: Stage 2 bypassed on YYYY-MM-DD — re-enter course-content-authoring before any real student sees this -->

   .
3. When generating

   course-data.js

   , set

   __thinDemo: true

   on each affected unit so the SPA renders a "本單元尚未填內容" badge — students who somehow land on a demo build can see it's not real.

course-content-authoring

• Every unit in

  course-data.js

  has an

  illustrations[]

  array with 1–3 entries. (The legacy single

  illustration: 'foo.png'

  field counts as 1; treat it as

  illustrations: [{ name: 'foo.png', kind: 'hero' }]

  for this check.)
• At least one entry per unit resolves to an existing file under

  assets/

  (the others may still be SVG fallback stubs while Stage 5 is mid-flight).
• If a unit genuinely needs no illustration (rare — e.g. a 5-min administrative slot, a quiz-only unit), record an explicit waiver:

  illustrations: [{ kind: 'waived', reason: '...' }]

  . Silence does not pass.

• assets/illustrations/

  (or your project's equivalent) contains the cover plus the per-unit images — not just the cover.

web-visual-assets

「目前有 N 個單元沒插圖（或全站只有封面）。學員一打開會覺得內容很空、像草稿。建議先用

web-visual-assets

跑一輪批次生圖（每單元 1–3 張，搭配 PNG-first / SVG-fallback），再進入電子書／企業包班分支 — 否則 PDF 一印出來就是大片留白。」

• Outline

  .md

  exists, but

  day{n}/content.md

  is missing or thin → Stage 2 (

  course-content-authoring

  ). Skipping to Stage 3 is gated — see Stage 2 Gate above.
• Content

  .md

  complete, but no

  course-data.js

  → Stage 3 (

  static-spa-conversion

  ).

• course-data.js

  exists, but

  index.html

  has no renderers / no local serve → Stage 3.
• SPA renders, but progress isn't persisted / no responsive / no theme → Stage 4.
• Site works but has placeholder

  <div>

  for images / 404 thumbnails / units missing illustrations → Stage 5 (

  web-visual-assets

  ).
• Site appears feature-complete but Stage 5 Image Coverage Floor not met → Stage 5 first; do NOT dispatch 5b/6 yet.
• Site is feature-complete (all gates + floor pass), user mentions corporate / in-house / shorter version → Stage 5b.
• Site is feature-complete (all gates + floor pass), user wants a printed / archived / shareable file → Stage 6.

1. Never skip stages forward. Don't generate Stage 3 SPA from a half-baked Stage 1 outline — the structural mismatches multiply. If the user wants to skip, say so explicitly.
2. Always trace back-references. When the user modifies a downstream artifact (e.g. "add unit u-6 to day 2"), update upstream (

   outline.md

   ) AND downstream (

   course-data.js

   , related visuals) in the same change. Half-updated sites accumulate technical debt very fast.
3. Course-specific knowledge belongs to the user's content, not to a skill. The sub-skills are intentionally agnostic to the topic of the course (AI workshop / cooking class / accounting training — same pipeline). If a sub-skill seems to be hardcoding domain examples, that's a smell.
4. Verification commands are part of the deliverable. When dispatching to Stage 3+, remind the user how to verify (

   npm run serve

   , then visit

   http://localhost:3000

   ). Static sites often fail silently when opened with

   file://

   (localStorage blocked).

• references/consistency-checklists.md

  — Read after every stage transition. Contains the full per-stage cross-artifact checklist (what to verify after Stage 1, 2, 3, ... 6, 5b). Catches "I changed X but forgot to update Y" bugs.

• references/scenarios.md

  — Read when the user's intent is ambiguous. Contains a dozen typical user prompts ("我有講義 .md 了", "客戶要濃縮版 + PDF") mapped to the exact sub-skill dispatch flow.

• references/troubleshooting.md

  — Read when something is reported broken. Maps symptoms ("素材連結 404", "進度勾選跑掉", "PDF 沒頁碼") to the most likely sub-skill / audit / verification path.

• references/design-rationale.md

  — Read when explaining the skill architecture itself, or when deciding whether a new feature deserves its own sub-skill vs. fitting into an existing one. Captures why the pipeline is shaped this way.

• Does not write any code itself — always dispatches to a sub-skill.
• Does not pick a CSS framework or build tool — assumes vanilla HTML/JS by default (see

  static-spa-conversion

  for why).
• Does not decide the course topic, audience, or pedagogy — that's the user's domain.