Course Content Authoring

Schema authority: all primitive field names (unit / concept / prompt / task / material / quiz / faq / illustration) come from
_shared/domain-primitives.md
. When this skill mentions a field, that file is the source of truth.
Filename convention (English-first): all generated files and directories use English names. The mapping from legacy Chinese names is in
_shared/domain-primitives.md
§0.

This skill produces the teaching substance of a course: the things a learner reads, copies, listens to, or works through. It anchors every artifact to the outline IDs from

course-outline-design

, so the next stage (SPA conversion) can wire them up mechanically.

Deliverables (Standard Layout)

course-package/   (your project's content root)
├── day{n}/
│   ├── outline.md           ← from outline stage (do NOT edit here)
│   └── content.md           ← THIS skill writes: lecture script, prompts, exercises, references
├── shared-scenario.md            ← from outline stage
├── supporting-docs.md            ← THIS skill writes: FAQ, environment setup, pre-reading
└── materials/                  ← THIS skill writes: standalone learner artifacts
    ├── README.md             ← index of materials
    └── *.md, *.csv, *.yaml   ← samples, templates, datasets

Material Types (Pick What Fits Your Course)

The example workshop uses these — they're examples, not requirements. Decide per course what makes sense:

Type	Format	When to use
Lecture script	`.md`	Per-day teaching narrative, embedded in `content.md`
Sample document	`.md`	A "before" artifact learners will improve (e.g. an FAQ, a policy doc)
Tabular dataset	`.csv` (UTF-8 BOM!)	Practice data for AI processing exercises
Structured config	`.yaml`	When the exercise involves declarative configuration
PDF reference	`.pdf`	Official documents (laws, regulations) — usually external sources
Prompt template	`.md` block	Domain-specific reusable prompts (this course uses RTFC framework, others may not — adapt to your course's pedagogy)
Quiz items	inline in `content.md` or separate	Pre-test, post-test, comprehension checks
Worksheets	`.md`	Fill-in templates learners complete

About prompt templates: This skill is agnostic to which prompt framework you use. RTFC (Role / Task / Format / Context) was used in the original workshop, but if your course teaches a different framework (e.g. CRISPE, COSTAR, plain examples), use that. Don't force RTFC into a course where it doesn't fit. The framework is part of the course content, not a property of this skill.

CSV Trap (Easy to Miss)

When generating CSV files that will be opened in Excel by non-developer learners, prepend a UTF-8 BOM (

const content = '' + headerRow + '\n' + dataRows.join('\n');

Without it, Excel on Windows mis-detects encoding and shows mojibake. Learners will think the file is broken. This bug was found late in the example workshop — bake it in from the start.

Anchor Everything to Outline IDs

Every artifact you produce must trace to a unit ID. Use this header pattern in lecture notes:

markdown

## u-3: {Unit title from outline.md}

**對應任務**: d2-u3-t1, d2-u3-t2
**對應素材**: 客訴處理SOP.md, FAQ官方版.md
**圖片需求 (illustrations)**:
- `day2-u3-hero.png` — hero / 主視覺：{學員角色} 在 {情境} 操作的場景圖（AI 生圖）
- `day2-u3-flow.svg` — 概念流程：{步驟 A → B → C}（手繪 SVG，含中文標籤）
- `day2-u3-example.png` — 結果範例截圖（選填）

{lecture content here}

Why: the SPA conversion stage will read these markers to auto-link tasks, materials, content, and visual asset slots. If you skip them, the SPA author has to re-read everything to figure out the wiring, and Stage 5 (

web-visual-assets

) has no spec to generate against — you end up with a site that has only a cover image.

Task IDs Are Forever

When writing task descriptions inside

content.md

, assign each task a stable ID (e.g.

d2-u3-t1

). These IDs will become localStorage keys in the deployed website. Three rules:

Never rename a published task ID. Students' progress is keyed to it.
Never reuse a deleted task ID. If you remove a task, the ID retires permanently.
Two formats coexist in practice (
```
d{n}-u{m}-t{k}
```
and
```
day{n}-u{m}-t{k}
```
). Pick one for new content; don't mix.

Quiz Item Discipline

If the course has a quiz, write items numbered sequentially (

q1

q2

, ...). Be aware these numbers will leak into multiple places once on the SPA:

The quiz array itself
A
```
qIndexToDay()
```
-style helper that maps each item to its source chapter (so wrong answers can link back)
Hardcoded strings in the SPA:
```
"結訓測驗（N題）"
```
, score display
```
— / N
```
, passing threshold
```
s >= K
```

Renumber-safe authoring: think of the quiz as append-only. If you delete

q3

, leave the slot empty in your draft and renumber only at the very last stable moment, with a checklist of all the places to update.

Hidden Materials Pattern

Some materials are for instructors only (answer keys, pre/post-test scoring) or conditional (only shown if a feature flag is on). Mark them explicitly in

materials/README.md

markdown

| 素材 | 對象 | 備註 |
|---|---|---|
| 員工差勤辦法.md | 學員 | Day 2 公開素材 |
| 結訓測驗解答.md | 講師 | 不要納入 SPA materials[]，僅講師端使用 |

The SPA conversion stage will read this column and exclude instructor-only items.

Anti-Patterns

Writing content before outline is locked — every back-edit cascades to multiple files.
Embedding prompt frameworks the course doesn't actually teach — if your course doesn't use RTFC, don't force-fit it just because the example template has it.
Quiz items without source-chapter mapping — when a learner gets one wrong, they need to know where to review. Tag every quiz item with the unit it came from.
Long flat material list with no instructor / learner distinction — by Day 4 the instructor doesn't know which file is what.
Forgetting CSV BOM — see above.

Completion Gate (Hard Rule — must pass before hand-off)

Before declaring "content draft complete" and suggesting

static-spa-conversion

, every item below must have a written artefact in the corresponding

.md

file (not just a verbal "yes"). Walk the user through them; if an artefact is thin or missing, ask one clarifying question and finish it before moving on.

Per-day
content.md
exists for every Day declared in
```
overview.md
```
```
每日主題
```
table. A Day file with only the title heading fails — it must contain unit sections.
Every outline unit ID has a matching
## u-{id}
section in its day's
```
content.md
```
. Run a quick diff: list of unit IDs in
```
day{n}/outline.md
```
must be a subset of
```
## u-
```
headings in
```
day{n}/content.md
```
. Missing sections fail the gate.
Every unit section has substance — at least one of: lecture script ≥ ~10 lines,
```
**對應任務**
```
listing real task IDs,
```
**對應素材**
```
listing real material filenames. A unit that only has a heading +
```
TODO
```
placeholder fails.
Every unit section declares
**圖片需求 (illustrations)**
with 1–3 entries. Each entry must specify (a) filename stem (e.g.
```
day2-u3-hero.png
```
), (b) image kind (
```
hero
```
/
```
diagram
```
/
```
screenshot
```
/
```
scene
```
), (c) one-line spec for the visual asset author. Units that genuinely need no image must declare a single waiver line:
```
- waived: {reason, e.g. 5-min admin slot}
```
. Silence does not pass.
Quiz items (if applicable) tagged with
sourceUnit
— every
```
q*
```
item points to a real unit ID so wrong answers can route students back to the source chapter. Untagged items fail.
materials/README.md
exists with the material index, distinguishing 學員 vs 講師 columns (see Hidden Materials Pattern above).

If the user pushes "可以了，先轉成網頁" before all items have written artefacts, refuse politely:

「Stage 2 還有 N 個單元沒寫實質內容（或沒設圖片需求）。直接進 Stage 3 會生出薄殼網頁，學員看到只有標題 + 沒插圖。先把第 X 項補上，大概 Y 分鐘，比之後重做網頁省好幾倍。」

If the user explicitly demands a thin demo (與

teaching-site

Stage 2 Override Policy 相同條件)：依照 orchestrator 文件的三步驟（標 stub 註解、設

__thinDemo: true

、明確告知學員顯示效果）才放行，不要在 Stage 2 內部偷偷放水。

Hand-off

When this stage finishes (Completion Gate passed), you should have:

Per-day
```
content.md
```
filled in, every outline unit ID covered by a
```
## u-{id}
```
section
Each unit section: lecture script + tasks + materials refs +
```
圖片需求 (illustrations)
```
1–3 entries
All material files in
```
materials/
```
with an index README distinguishing 學員 / 講師 items
Quiz draft (if applicable) numbered
```
q1..qN
```
with
```
sourceUnit
```
source-chapter tags
Every artifact traceable to an outline unit ID

Tell the user: "content draft complete. Next stage (

static-spa-conversion

) will convert this into

course-data.js

index.html

, including an

illustrations: []

array per unit derived from your

圖片需求

blocks. After Stage 3/4,

web-visual-assets

will fulfil those slots — your spec lines become its prompt input. Don't change unit IDs or task IDs from this point — they'll become localStorage keys."

course-content-authoring

NPX Install

Tags

SKILL.md Content