Scaffold Exercises
Scaffold course exercise folders (sections, problems, solutions, explainers) that pass ai-hero-cli lint and commit cleanly.
Overview
scaffold-exercises is an agent skill for the Build phase that creates lint-clean exercise directory structures with sections, variants, and stub readmes for course repos.
Install
npx skills add https://github.com/vinvcn/mattpocock-skills-zh-cn --skill scaffold-exercisesWhat is this skill?
- Naming: XX-section-name under exercises/ and XX.YY-exercise-name with dash-case
- Variants: problem/ (TODOs), solution/, explainer/—default explainer stubs when unspecified
- Required non-empty readme.md per variant; code variants need main.ts (>1 line)
- 5-step workflow: parse plan → mkdir → stub readmes → pnpm ai-hero-cli internal lint → fix until pass → git commit
- Lint gate before commit
- 5-step workflow ending in lint and git commit
- 3 exercise variant types: problem, solution, explainer
Adoption & trust: 478 installs on skills.sh; 485 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a course plan but no consistent exercise folders, and your repo fails lint on empty readmes, bad links, or wrong naming.
Who is it for?
Course authors and indie builders maintaining ai-hero-cli exercise monorepos who add sections frequently.
Skip if: Projects without pnpm ai-hero-cli lint, or single-file tutorials with no exercises/ convention.
When should I use this skill?
User wants to scaffold exercises, create exercise stubs, or set up a new course section (per SKILL.md description).
What do I get? / Deliverables
You get XX.YY exercise paths with variant stubs, a passing pnpm ai-hero-cli internal lint run, and a git commit ready for students or agents to fill in.
- exercises/XX-section/XX.YY-name/ variant folders with readme stubs
- Lint-clean tree ready for git commit
Recommended Skills
Journey fit
How it compares
Curriculum scaffolding workflow—not a generic markdown folder generator.
Common Questions / FAQ
Who is scaffold-exercises for?
Solo builders and educators maintaining structured exercise repos (Matt Pocock / AI Hero style) who want agents to create directories that pass internal lint.
When should I use scaffold-exercises?
During Build docs/curriculum work when you scaffold exercises, create exercise stubs, or set up a new course section from a plan.
Is scaffold-exercises safe to install?
Review Security Audits on this Prism page; the skill runs mkdir, lint, and git commit—use only in repos you control.
SKILL.md
READMESKILL.md - Scaffold Exercises
# Scaffold Exercises 创建能通过 `pnpm ai-hero-cli internal lint` 的 exercise directory structures，然后用 `git commit` 提交。 ## Directory naming - **Sections**：`exercises/` 下的 `XX-section-name/`（例如 `01-retrieval-skill-building`） - **Exercises**：section 下的 `XX.YY-exercise-name/`（例如 `01.03-retrieval-with-bm25`） - Section number = `XX`，exercise number = `XX.YY` - Names 使用 dash-case（小写、连字符） ## Exercise variants 每个 exercise 至少需要这些 subfolders 中的一个： - `problem/` — student workspace，包含 TODOs - `solution/` — reference implementation - `explainer/` — conceptual material，不含 TODOs 创建 stub 时，除非 plan 指定其他 variant，否则默认使用 `explainer/`。 ## Required files 每个 subfolder（`problem/`、`solution/`、`explainer/`）都需要一个 `readme.md`，要求： - **非空**（必须有真实内容，即使只有一行 title 也可以） - 没有 broken links 创建 stub 时，生成带 title 和 description 的最小 readme： ```md # Exercise Title Description here ``` 如果 subfolder 有 code，还需要 `main.ts`（>1 行）。但对 stubs 来说，readme-only exercise 可以接受。 ## Workflow 1. **Parse the plan** — 提取 section names、exercise names 和 variant types 2. **Create directories** — 对每个 path 执行 `mkdir -p` 3. **Create stub readmes** — 每个 variant folder 一个带 title 的 `readme.md` 4. **Run lint** — 执行 `pnpm ai-hero-cli internal lint` 验证 5. **Fix any errors** — 迭代直到 lint 通过 ## Lint rules summary linter（`pnpm ai-hero-cli internal lint`）检查： - 每个 exercise 有 subfolders（`problem/`、`solution/`、`explainer/`） - 至少存在 `problem/`、`explainer/` 或 `explainer.1/` 之一 - primary subfolder 中存在非空 `readme.md` - 没有 `.gitkeep` files - 没有 `speaker-notes.md` files - readmes 中没有 broken links - readmes 中没有 `pnpm run exercise` commands - 除非是 readme-only，否则每个 subfolder 都需要 `main.ts` ## Moving/renaming exercises 重新编号或移动 exercises 时： 1. 使用 `git mv`（不是 `mv`）重命名 directories，保留 git history 2. 更新 numeric prefix 以维持顺序 3. 移动后重新运行 lint Example: ```bash git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings ``` ## Example: stubbing from a plan 给定这样的 plan： ``` Section 05: Memory Skill Building - 05.01 Introduction to Memory - 05.02 Short-term Memory (explainer + problem + solution) - 05.03 Long-term Memory ``` 创建： ```bash mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution} mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer ``` 然后创建 readme stubs： ``` exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory" exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory" exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory" exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory" exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory" ```