mp-scaffold-exercises

---
name: mp-scaffold-exercises
description: "Use when scaffolding course exercise directories (sections, problems, solutions, explainers) that pass `pnpm ai-hero-cli internal lint` — Matt's AI Hero course tooling convention."
source: https://github.com/mattpocock/skills/blob/main/skills/misc/scaffold-exercises/SKILL.md
generated: 2026-05-12T18:05:14.802Z
category: tool
audience: engineers
---

## When to use

- Stubbing a new section of exercises from a plan with section / exercise / variant names
- Renumbering or moving exercises while preserving git history
- Fixing lint failures from `pnpm ai-hero-cli internal lint` — missing readme.md, broken links, .gitkeep files
- Working inside the AI Hero course repo or a fork that shares the `exercises/` convention

## Key concepts

### section / exercise numbering

Sections live at `exercises/XX-section-name/` (e.g. `01-retrieval-skill-building`). Exercises at `exercises/XX.YY-exercise-name/` (e.g. `01.03-retrieval-with-bm25`). Section number = XX, exercise number = XX.YY. Names are lowercase-dash-case.

### exercise variants — problem / solution / explainer

Each exercise needs at least one of: `problem/` (student workspace with TODOs), `solution/` (reference implementation), `explainer/` (concept-only, no TODOs). When stubbing without explicit plan info, default to `explainer/`.

### readme.md required, non-empty

Each variant subfolder needs a `readme.md` with real content (even a single title line works) and no broken links. The lint tolerates readme-only exercises, but bare empty folders fail.

### main.ts when there's code

If the variant subfolder has actual code (not just a readme), it also needs a `main.ts` with >1 line. For stubs, readme-only is fine — no `main.ts` required.

### git mv for renames

Use `git mv` (NOT plain `mv`) to rename / renumber exercise directories. Plain `mv` loses git history and makes blame on the renumbered file useless.

### no .gitkeep, no speaker-notes.md

The linter explicitly bans `.gitkeep` files (use a real readme instead) and `speaker-notes.md` (handled separately). Also bans `pnpm run exercise` commands in readmes — they're a stale convention.

## API reference

```
Workflow
```

Five-step loop ending with the AI Hero lint pass. Iterate steps 4–5 until clean.

```
1. Parse the plan — extract section / exercise / variant names
2. Create directories with mkdir -p
3. Create stub readmes — one per variant folder, title + 1-line description
4. Run `pnpm ai-hero-cli internal lint`
5. Fix errors, re-run until clean
```

```
Stubbing from a plan
```

Concrete example: given a plan with three exercises in Section 05, produce dir tree + readmes.

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

# then per dir:
echo '# Introduction to Memory' > exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md
```

```
Renumbering with history preserved
```

Use git mv to keep blame coherent.

```
git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
```

```
Minimal readme template
```

Smallest content that passes the lint.

```
# Exercise Title

Description here
```

## Gotchas

- This skill targets Matt's AI Hero course conventions (`pnpm ai-hero-cli internal lint`) — it won't work in arbitrary monorepos without that CLI.
- Default to `explainer/` when stubbing without an explicit plan — student-facing problem/solution sets need real content, not stubs.
- Every variant subfolder must have a non-empty `readme.md`. Empty file or missing file = lint fail.
- No `.gitkeep` files. The linter rejects them — use a real `readme.md` instead.
- No `speaker-notes.md` and no `pnpm run exercise` commands in readmes — both are explicitly banned.
- Use `git mv` for renames so blame survives. Plain `mv` + add/remove fragments history.
- If a subfolder has code, it needs both a `readme.md` AND a `main.ts` (>1 line). Stubs are exempt from main.ts.
- Run lint after every move — error messages are clearer when one batch of edits is being evaluated, not three layered batches.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/misc/scaffold-exercises/SKILL.md on 2026-05-12T18:05:14.802Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-scaffold-exercises/SKILL.md