Course Forge

Turn a knowledge document or narration script into a record-ready, click-driven 16:9 web presentation — with optional TTS audio, chunk-based subtitles, and either web embed or MP4 export.

English · 中文文档 · SKILL entry

---

What it does

You provide an article or script. The skill walks an agent through:

1. Writing narration (script.md) and a per-chapter build plan (outline.md)
2. Aligning with you on the script, outline, theme, source assets, and dev mode
3. Scaffolding a Vite + React + TS project, then building chapters one-by-one (chapter 1 is always built in the main thread as the anchor)
4. Optionally synthesizing audio via pluggable TTS (MiniMax / OpenAI / Edge / custom)
5. Embedding into a web app, or auto-recording as MP4

Output is a static dist/ — deployable anywhere.

---

Install

# Recommended — skills CLI
npx skills add xmwengxing/course-forge

# Or — manual clone
git clone https://github.com/xmwengxing/course-forge.git
cp -r course-forge /your-project/.opencode/skills/

For Claude Code, also available as a plugin marketplace entry: /plugin marketplace add xmwengxing/course-forge.

---

Quick start

# 1. Install (see above)

# 2. Scaffold a courseware project
bash .opencode/skills/course-forge/scripts/scaffold.sh ./my-course --theme=chalk-garden

# 3. Hand the source document to your agent and say:
#    "Create a course from docs/my-knowledge-doc.md using course-forge"

The agent will produce script.md + outline.md, walk you through the 5-point checkpoint, then build chapters. See SKILL.md for the full workflow.

---

Built-in themes

Six themes, each a distinct design DNA — not just color swaps. Pick by mood, or copy one as the starting point for your own:

midnight-press	chalk-garden	paper-press	newsroom	blueprint	bauhaus-bold
dark cinematic	handwritten chalk	light editorial	print/serif	tech blueprint	modernist

Full signatures, design tokens, and a "create your own" walkthrough live in references/THEMES.md.

---

Workflow at a glance

Phase 1  Content       →  script.md + outline.md
                          [Checkpoint Plan]  align 5 things
Phase 2  Web build     →  scaffold + chapters (chapter 1 = anchor)
                          [User review]      anchor must be approved
                          →  chapters 2..N   (per-chapter / sequential / parallel)
Phase 3  Audio (opt.)  →  TTS synthesis + chunk-based subtitles
Phase 4  Deploy        →  embed (new-tab / iframe / DB)  OR  record as MP4

Hard stops are the [] lines — the agent must pause for human review at every one. For phase details and what to read at each stage, see SKILL.md § "File reading guide".

---

Course hierarchy (course mode)

Course      — single domain or full-length curriculum (e.g. "Intro to X")
Segment     — S1..SN, themed block within a course (导入 / 精讲 / 案例 / 收官 / ...)
Chapter     — 30-60s screen = N steps, the unit the skill actually builds
Step        — single narration beat = full-screen content

Single-video mode (most common) skips the Course and Segment tiers — course.json is optional and can be deleted. See references/COURSE-MODE.md.

---

Architecture: the invariants

Three things hold the whole system together. Break any one and chapters, audio, and chapter menu break with it.

1. narrations.ts is the single source of truth — array length must equal max(if (step === N)) + 1 in the chapter's .tsx. Five artifacts stay aligned by obeying this one rule: script.md, outline.md, chapter code, chapters.ts registry, and audio files.
2. Theme = CSS tokens + JSON metadata — switching themes means copying themes/<id>/tokens.css over <project>/src/styles/tokens.css. Components never import theme-specific values.
3. Each chapter renders into a fixed 1920×1080 stage — CSS transform: scale() via useStageScale. Author inside that coordinate system, not viewport pixels.

---

When to use it

Good fit	Less ideal
Standardized training at scale (1000+ learners)	Content where the human instructor's presence carries the message
Content that needs frequent small updates	Physical/lab/hands-on demonstrations
Quiz / decision-tree / drag-and-drop exercises	Live Q&A that needs real-time adaptation
Cost-sensitive delivery (zero marginal cost per learner)	Brand-new content where the script needs many drafts
Searchable, indexable, analytics-rich content	Offline-on-a-phone-only delivery (works, but MP4 is simpler)

---

Compatibility

Runtime	Skill location
OpenCode	.opencode/skills/<name>/
Claude Code	.claude/skills/<name>/ or plugin marketplace
Cursor	.agents/skills/<name>/
Codex CLI	.codex/skills/<name>/

Requires Node 20+ for scaffolded projects. TTS requires network access to whichever provider you pick.

Upgrading from a previous version

⚠️ If you upgrade from a version before course.json static import was introduced: delete any public/course.json (or public/course-*.json) in your scaffolded project. The current useCourseLoader imports course.json directly from the project root, so the public/ copy is dead weight and can drift out of sync. After deleting, run npm run build once to verify.

The first time you pull a new version of this skill, in your scaffolded project run:

npm install       # or: pnpm install / yarn install
bash scripts/check-course-json-sync.sh   # exit 0 = clean

---

Documentation map

File	Read when
SKILL.md	Always first — workflow overview + per-phase reading guide
references/CHAPTER-CRAFT.md	Writing each chapter — single source of truth for what makes a chapter pass review
references/SCRIPT-STYLE.md	Phase 1 — turning an article into narration
references/OUTLINE-FORMAT.md	Phase 1 — the outline.md schema and chapter-split rules
references/COURSE-MODE.md	Phase 1/2 — only if building a multi-segment course
references/THEMES.md	Checkpoint Plan / any time you pick or change a theme
references/AUDIO.md	Phase 3 — TTS pipeline, providers, subtitle timing
references/RECORDING.md	Phase 4 — auto-record the running site as MP4
references/DEPLOYMENT.md	Phase 4 — embed into an existing web app
references/ANIMEJS-GUIDE.md	Writing a chapter that needs real animation or physics-style drag

---

License

MIT © course-forge contributors