Teaching Site — Main Entry Point
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 (
,
,
, 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:
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.
This is the top-level skill for producing an interactive teaching website. It coordinates 10 specialised sub-skills covering every stage from blank-slate outline to delivered PDF ebook.
When This Skill vs. a Sub-Skill
-
- 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 ("做電子書" → ).
- You're already deep into one stage and don't need pipeline overview.
- Another skill is dispatching here for a focused subtask.
Both paths converge — sub-skills can be reached either by direct trigger or via this skill's dispatch.
The Production Pipeline
A teaching site is built in five core layers, with two optional derivative layers at the end:
[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
Stages 1–5 are usually traversed in order, but users often jump back (add a unit → must update outline AND course-data.js AND any related visual). Catching these back-references is this skill's main value-add.
Stages 5b and 6 are downstream consumers of the finished site. They read but never modify the canonical site. Do not invoke them while Stages 1–5 are still in flux — the rework cost is high.
Sub-Skill Dispatch Table
Invoke the matching sub-skill via your agent's skill activation mechanism (Claude Code:
tool, Codex:
tool, Antigravity / Gemini CLI:
) when the matching stage is active:
| Stage | Sub-skill | Trigger phrases |
|---|
| 1 | | "規劃課程", "課程大綱", "幾天怎麼排", "學習目標" |
| 2 | | "寫講義", "補素材", "出測驗題", "提示詞範本" |
| 3 | | "做成網頁", "轉成 SPA", "course-data.js", "render 函式" |
| 4 | | "加進度勾選", "響應式", "暗色模式", "縮放", "scrollspy" |
| 5 | | "插圖", "工具截圖", "QR", "講師卡", "地圖" |
| 5b | | "企業包班", "濃縮版", "客製化", "壓縮成一天" |
| 6 | | "做電子書", "產 PDF", "印給學員", "DOCX 交付" |
| ╳ | | "驗證網頁", "RWD 驗證", "Playwright 測試", "截圖比對" |
| ╳ | | "盤點內容", "稽核資產", "找缺圖", "三處同步檢查" |
| ╳ | teaching-site-design-system
| "視覺風格", "設計系統", "色票", "字體", "玻璃卡片" |
The last three (marked ╳) are cross-cutting — not tied to a stage. The first two (verification / audit) are the safety net for runtime behaviour and cross-file references. The third (design-system) is the visual authority every stage reads from.
Stage 1 Gate (Hard Rule — read before any dispatch)
Before dispatching to ANY stage (including 2–6, 5b, and the cross-cutting skills), confirm Stage 1 deliverables exist on disk:
Shared scenario (
) is
optional — it's a downstream decision handled by
's Completion Gate, not an entry requirement here.
If either of the two is missing or only a stub: do NOT dispatch downstream, even if the user explicitly named a later stage ("做電子書", "幫我寫 quiz"). Dispatch to
first and tell the user:
「我看到還沒有完整的課程綱要 — 直接跳到 Stage N 會讓後面每改一次 outline 就連動多個檔案重做。先用
把 outline 鎖定，大概 10 分鐘決策，省下後續數小時 rework。」
Stage 1 Override Policy (3-bullet escape hatch)
If the user explicitly insists on skipping the gate ("我知道，先做就好", "skip the outline, just do X"), proceed under these conditions:
- Ask them to paste 3 bullets in chat before any downstream action:
- 對象：一句話描述學員是誰 + 先備知識
- 總時數 + 每日時段：例如「2 天 × 6 小時」
- 每日主題：Day 1 / Day 2 / ... 各一行
- Save those 3 bullets verbatim into a stub (mark it
<!-- stub created via Stage 1 Gate override on YYYY-MM-DD -->
- If the user refuses even the 3-bullet stub, fall back to the strict path — refuse the override and dispatch to .
The stub is the audit trail: future sessions reading this site can immediately see Stage 1 was bypassed and recover context.
Stage 2 Gate (Hard Rule — read before dispatching to Stage 3+)
After Stage 1 Gate passes, before dispatching to Stage 3 (
), Stage 5b, or Stage 6, confirm Stage 2 deliverables exist on disk:
If any item fails: do NOT dispatch to Stage 3+, even if the user explicitly named a later stage. Dispatch to
first and tell the user:
「outline 在，但 Day {n} 的
{缺/空殼/單元 u-{id} 沒寫}。直接做網頁會生出薄薄的殼 — 學員看到的只是標題清單，沒有實質教學內容。先用
把每個單元的 lecture / tasks / 圖片需求補完，比之後重做整套網頁省好幾倍時間。」
Stage 2 Override Policy (thin-demo escape hatch)
If the user explicitly insists on a thin demo ("先做殼就好", "我只要 demo 給客戶看版型", "skip content"), proceed under these conditions:
- State explicitly in chat what they're trading away: thin demo will have unit titles only, no lecture body, placeholder instead of illustrations, tasks as empty checkboxes.
- Mark every affected (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 -->
- When generating , set on each affected unit so the SPA renders a "本單元尚未填內容" badge — students who somehow land on a demo build can see it's not real.
Without all three, do not proceed. Refuse and dispatch to
.
Stage 5 Image Coverage Floor (Hard Rule — applies before declaring "site feature-complete")
A site that ships with only a cover image and bare text feels skeletal — learners disengage in the first scroll. Before declaring Stages 1–5 done (and therefore eligible for Stage 5b / 6 dispatch), confirm:
If unmet: dispatch to
and tell the user:
「目前有 N 個單元沒插圖（或全站只有封面）。學員一打開會覺得內容很空、像草稿。建議先用
跑一輪批次生圖（每單元 1–3 張，搭配 PNG-first / SVG-fallback），再進入電子書／企業包班分支 — 否則 PDF 一印出來就是大片留白。」
This floor is checked after Stage 4 finishes (interactivity wired) and before dispatching to Stage 5b or 6. Stage 5b / 6 inherit whatever images exist; if you skip the floor, the corporate brochure and the PDF ebook will both ship empty.
How to Detect the Current Stage
After Stage 1 Gate AND Stage 2 Gate pass, look for these signals to pick the right downstream stage:
- Outline exists, but is missing or thin → Stage 2 (). Skipping to Stage 3 is gated — see Stage 2 Gate above.
- Content complete, but no → Stage 3 ().
- exists, but 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 for images / 404 thumbnails / units missing illustrations → Stage 5 ().
- 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.
Ambiguous? Ask one short question, then dispatch. Don't try to do all stages at once — the cross-stage rework cost is high.
Operating Principles
-
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.
-
Always trace back-references. When the user modifies a downstream artifact (e.g. "add unit u-6 to day 2"), update upstream (
) AND downstream (
, related visuals) in the same change. Half-updated sites accumulate technical debt very fast.
-
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.
-
Verification commands are part of the deliverable. When dispatching to Stage 3+, remind the user how to verify (
, then visit
). Static sites often fail silently when opened with
(localStorage blocked).
Reference Files (Read When Needed)
When you need deeper detail than this entry point provides, read the appropriate reference:
-
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.
-
— 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.
What This Skill Does NOT Do
- 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 for why).
- Does not decide the course topic, audience, or pedagogy — that's the user's domain.