# Teaching Site

> Use this skill as the main entry point whenever the user wants to build, plan, or evolve an interactive teaching website / course microsite / workshop landing page — from a blank slate, from existing course materials, or any state in between. Triggers on broad phrases like "做課程網站", "做教學網頁", "做工作坊網站", "把講義變網頁", "course microsite", "workshop site", "interactive lesson page", "multi-day curriculum w…

- **Type:** Skill
- **Install:** `agentstack add skill-kevintsai1202-teaching-site-skills-teaching-site`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kevintsai1202](https://agentstack.voostack.com/s/kevintsai1202)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kevintsai1202](https://github.com/kevintsai1202)
- **Source:** https://github.com/kevintsai1202/teaching-site-skills/tree/main/teaching-site

## Install

```sh
agentstack add skill-kevintsai1202-teaching-site-skills-teaching-site
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](../_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.

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

- **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.

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: `Skill` tool, Codex: `skill` tool, Antigravity / Gemini CLI: `activate_skill`) when the matching stage is active:

| Stage | Sub-skill | Trigger phrases |
|---|---|---|
| 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` | "企業包班", "濃縮版", "客製化", "壓縮成一天" |
| 6 | `course-ebook-publishing` | "做電子書", "產 PDF", "印給學員", "DOCX 交付" |
| ╳ | `web-visual-verification` | "驗證網頁", "RWD 驗證", "Playwright 測試", "截圖比對" |
| ╳ | `web-content-audit` | "盤點內容", "稽核資產", "找缺圖", "三處同步檢查" |
| ╳ | `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:

- [ ] 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.

**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 `course-outline-design` first and tell the user:

> 「我看到還沒有完整的課程綱要 — 直接跳到 Stage N 會讓後面每改一次 outline 就連動多個檔案重做。先用 `course-outline-design` 把 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:

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 ``) 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`.

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 (`static-spa-conversion`), Stage 5b, or Stage 6, confirm Stage 2 deliverables exist on disk:

- [ ] 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.

**If any item fails:** do NOT dispatch to Stage 3+, even if the user explicitly named a later stage. Dispatch to `course-content-authoring` first and tell the user:

> 「outline 在，但 Day {n} 的 `content.md` {缺/空殼/單元 u-{id} 沒寫}。直接做網頁會生出薄薄的殼 — 學員看到的只是標題清單，沒有實質教學內容。先用 `course-content-authoring` 把每個單元的 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:

1. 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.
2. Mark every affected `day{n}/content.md` (create as stub if missing) with header comment ``.
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.

Without all three, do not proceed. Refuse and dispatch to `course-content-authoring`.

## 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:

- [ ] 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.

**If unmet:** dispatch to `web-visual-assets` and tell the user:

> 「目前有 N 個單元沒插圖（或全站只有封面）。學員一打開會覺得內容很空、像草稿。建議先用 `web-visual-assets` 跑一輪批次生圖（每單元 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 `.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 `` 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.

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

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).

## 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.

- **`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.

## 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 `static-spa-conversion` for why).
- Does not decide the course topic, audience, or pedagogy — that's the user's domain.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kevintsai1202](https://github.com/kevintsai1202)
- **Source:** [kevintsai1202/teaching-site-skills](https://github.com/kevintsai1202/teaching-site-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kevintsai1202-teaching-site-skills-teaching-site
- Seller: https://agentstack.voostack.com/s/kevintsai1202
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.