course-content-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Schema 权威来源：所有原始字段名（unit / concept / prompt / task / material / quiz / faq / illustration）均来自
_shared/domain-primitives.md
。当此技能提及某个字段时，该文件为权威依据。
文件名规范（英文优先）：所有生成的文件和目录均使用英文名称。旧版中文名称与英文的映射关系见
_shared/domain-primitives.md
第0节。

本技能生成课程的教学核心内容：即学员阅读、复制、收听或实操的内容。所有制品均锚定

course-outline-design

生成的大纲ID，以便下一阶段（SPA转换）能自动关联内容。

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

course-package/   (你的项目内容根目录)
├── day{n}/
│   ├── outline.md           ← 来自大纲阶段（请勿在此编辑）
│   └── content.md           ← 本技能生成：讲义脚本、提示词、练习、参考资料
├── shared-scenario.md            ← 来自大纲阶段
├── supporting-docs.md            ← 本技能生成：FAQ、环境搭建说明、预读材料
└── materials/                  ← 本技能生成：独立学员制品
    ├── README.md             ← 素材索引
    └── *.md, *.csv, *.yaml   ← 示例、模板、数据集

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.

示例工作坊使用以下类型——它们是示例而非强制要求。请根据课程需求选择合适的类型：

类型	格式	使用场景
讲义脚本	`.md`	每日教学叙事内容，嵌入 `content.md` 中
示例文档	`.md`	学员将进行优化的「初始」制品（如FAQ、政策文档）
表格数据集	`.csv` （需UTF-8 BOM！）	AI处理练习用的实操数据
结构化配置	`.yaml`	练习涉及声明式配置时使用
PDF参考文档	`.pdf`	官方文档（法律、法规）——通常为外部资源
Prompt模板	`.md` 块	特定领域的可复用提示词（本课程使用RTFC框架，其他课程可根据教学方法调整）
测验题目	嵌入 `content.md` 或单独存放	预测试、后测试、理解检测
工作表	`.md`	学员需填写的模板

关于Prompt模板：本技能不绑定特定提示词框架。示例工作坊使用RTFC（Role / Task / Format / Context）框架，但如果你的课程教授其他框架（如CRISPE、COSTAR或普通示例），请使用对应框架。不要在不适用的课程中强行使用RTFC——框架是课程内容的一部分，而非本技能的固有属性。

CSV Trap (Easy to Miss)

CSV 陷阱（易忽略点）

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.

当生成供非开发者学员用Excel打开的CSV文件时，需添加UTF-8 BOM（

）：

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

如果不添加，Windows系统上的Excel会错误识别编码，导致乱码。学员会认为文件损坏。这个问题在示例工作坊后期才被发现——请从一开始就做好处理。

Anchor Everything to Outline IDs

所有内容锚定大纲ID

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

markdown

undefined

你生成的每一个制品都必须关联到单元ID。讲义中请使用以下标题格式：

markdown

undefined

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

u-3: {来自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.

對應任務: 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
```
— 結果範例截圖（選填）

{讲义内容}


原因：SPA转换阶段会读取这些标记，自动关联任务、素材、内容**以及视觉资源占位符**。如果跳过这些标记，SPA创作者需要重新梳理所有内容的关联关系，且第5阶段（`web-visual-assets`）将没有生成依据——最终网站可能只有封面图。

Task IDs Are Forever

任务ID不可变更

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.

在

content.md

中编写任务描述时，需为每个任务分配稳定的ID（如

d2-u3-t1

）。这些ID将成为部署后网站的localStorage键。需遵守三条规则：

切勿重命名已发布的任务ID——学员的进度以此为标识。
切勿复用已删除任务的ID——如果移除任务，该ID永久作废。
两种格式共存（
```
d{n}-u{m}-t{k}
```
和
```
day{n}-u{m}-t{k}
```
）。新内容请选择一种格式，不要混用。

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.

如果课程包含测验，请按顺序编号题目（

q1

q2

, ...）。请注意这些编号会在SPA的多个地方出现：

测验数组本身
```
qIndexToDay()
```
类辅助函数，用于将每个题目映射到对应的章节（以便答错时跳转复习）
SPA中的硬编码字符串：
```
"結訓測驗（N題）"
```
、分数显示
```
— / N
```
、及格阈值
```
s >= K
```

安全重命名方法：将测验视为仅可追加的内容。如果删除

q3

，请在草稿中保留空位，仅在最终稳定阶段统一重命名，并核对所有需要更新的位置。

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.

部分素材仅面向讲师（答案、测验评分标准）或有条件显示（仅在功能标志开启时显示）。请在

materials/README.md

中明确标记：

markdown

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

SPA转换阶段会读取此列，排除仅面向讲师的素材。

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.

大纲未锁定就开始编写内容——每一次回溯修改都会影响多个文件。
嵌入课程未教授的提示词框架——如果你的课程不使用RTFC，不要因为示例模板有就强行套用。
测验题目未关联章节——学员答错时，需要知道去哪里复习。请为每个测验题目标记对应的单元。
素材列表冗长且未区分讲师/学员——到第4天时，讲师将无法区分各个文件的用途。
忘记添加CSV BOM——见上文说明。

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 內部偷偷放水。

在宣布「内容草稿完成」并建议进入

static-spa-conversion

之前，以下每一项都必须在对应的

.md

文件中有书面制品（不能只是口头确认）。请引导用户逐一检查；如果制品内容单薄或缺失，请提出一个澄清问题并补充完整后再推进。

每个大纲中声明的Day都有对应的
content.md
。仅包含标题的Day文件视为不合格——必须包含单元章节。
每个大纲单元ID在对应Day的
content.md
中都有匹配的
## u-{id}
章节。快速核对：
```
day{n}/outline.md
```
中的单元ID列表必须是
```
day{n}/content.md
```
中
```
## u-
```
标题的子集。缺失章节视为不合格。
每个单元章节都有实质内容——至少包含以下一项：约10行以上的讲义脚本、
```
**對應任務**
```
列出真实任务ID、
```
**對應素材**
```
列出真实素材文件名。仅包含标题+
```
TODO
```
占位符的单元视为不合格。
每个单元章节都声明了
**圖片需求 (illustrations)**
，包含1-3项内容。每一项必须指定：(a) 文件主干名（如
```
day2-u3-hero.png
```
），(b) 图片类型（
```
hero
```
/
```
diagram
```
/
```
screenshot
```
/
```
scene
```
），(c) 视觉资源创作者的单行说明。确实不需要图片的单元必须声明一条豁免：
```
- waived: {原因，如5分钟行政环节}
```
。未声明视为不合格。
测验题目（如有）标记了
sourceUnit
——每个
```
q*
```
题目都指向真实的单元ID，以便答错时引导学员回到对应章节复习。未标记的题目视为不合格。
materials/README.md
已存在，包含素材索引，并区分「學員」和「講師」列（见上文隐藏素材模式）。

如果用户在所有项都完成前提出「可以了，先轉成網頁」，请礼貌拒绝：

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

如果用户明确要求生成精简演示版（与

teaching-site

Stage 2 覆盖政策条件相同）：请按照编排器文档的三步操作（标记占位注释、设置

__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."

当本阶段完成（通过完成检查门），你应已生成：

填充完成的每日
```
content.md
```
，每个大纲单元ID都有对应的
```
## u-{id}
```
章节
每个单元章节：讲义脚本 + 任务 + 素材引用 + 1-3项
```
圖片需求 (illustrations)
```
```
materials/
```
目录下的所有素材文件，以及区分学员/讲师的索引README
测验草稿（如有），按
```
q1..qN
```
编号并标记
```
sourceUnit
```
章节来源
所有制品均可追溯到大纲单元ID

告知用户：「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.」