scaffold-exercises lays out the empty folders for a course's exercises, from a plan you give it. It turns a list of sections and exercises into numbered folders, each with a stub readme.md, checks them with a linter and commits them.
The layout it follows:
A section is XX-section-name/ inside exercises/, such as 01-retrieval-skill-building.
An exercise is XX.YY-exercise-name/ inside a section, such as 01.03-retrieval-with-bm25. Names are dash-case: lowercase, with hyphens.
Each exercise needs at least one of three subfolders: problem/ (the student's workspace, with TODOs), solution/ (the reference answer) or explainer/ (ideas only, no TODOs). When stubbing, it picks explainer/ unless the plan says otherwise.
Each of those subfolders needs a readme.md that isn't empty. A title line is enough.
When to use it
Use it when you're setting up a new section of a course that uses this exercise layout, and you already have the plan: the section's name, each exercise's name and which subfolders each one needs.
Use it also to renumber or move exercises. It renames folders with git mv rather than mv, so their git history is kept, and updates the number prefixes to keep the order.
It's model-invoked: an agent can load it on its own when you ask to scaffold exercises or set up a new course section.
When not to use it
You want to learn a topic yourself, over several sessions: use teach. teach writes lessons for you to study. scaffold-exercises only makes empty folders for a course other people will take.
Your course isn't laid out in exercises/ folders like the ones above. Every rule it follows, and its lint step, comes from that one layout.
What it needs to start
A plan: section names, exercise names and the subfolders each exercise needs.
A repo with an exercises/ folder, where its lint command, pnpm ai-hero-cli internal lint, can run.
ai-hero-cli removed that command in 0.6.0, so with a current CLI the step can't run (see Going deeper).
What it creates
It works in five steps: parse the plan, create the folders with mkdir -p, write the stub readmes, run the linter, and fix errors until the linter passes. At the end you have:
one folder per section and per exercise, each exercise with its subfolders;
one stub readme.md in every subfolder, with a title and a short description;
a git commit holding all of it.
Going deeper
5 min read · Going deeper not read
Why it exists
Matt added it on 2026-02-20 with one line of purpose: "Create exercise directory structures that pass pnpm ai-hero-cli internal lint." By the 2026-10-29 pin commit that line also says "then commit with git commit."
That lint command belongs to ai-hero-cli, a tool "typically pre-installed in AI Hero exercise repositories." So the problem is laying out a course's exercises/ folders in a way that tool accepts. The Skill's own examples, such as 01-retrieval-skill-building, are the names of a real section in an AI Hero course repo (see "A real example").
It sits in Matt's misc bucket. Two dated changes set its status:
On 2026-07-01 Matt demoted the whole bucket. His commit message says misc skills "are no longer installable via the plugin or listed in the top-level README". The same commit notes "the non-promoted status in the misc bucket README". That README labels the bucket: "Tools I keep around but rarely use, not promoted in the plugin."
On 2026-10-06 he froze it. His note on frozen misc skills says "Bug reports, feature requests and PRs against them are closed." His reason, in his own words: "I'm not running them day to day, so I can't tell whether a fix is right or notice when one breaks something else."
So it has no aihero.dev docs page either: his repo's notes say misc skills "get no docs page". And his advice if one breaks for you: "install it with skills.sh and fix your copy: the files are yours to edit."
Citations (78)
From snapshot/skills/scaffold-exercises/SKILL.md, line 3: “Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.”
Matt's note freezing the misc Skills, scaffold-exercises among them. From github.com, 30 October 2026.
How it works underneath
The Skill is a checklist written for one linter. That linter lives in ai-hero-cli, Matt's "command-line interface tool designed to help students navigate and run AI Hero exercises efficiently."
Its changelog shows the linter arriving one rule at a time, and the Skill's "Lint rules summary" mirrors those rules:
"Added internal/lint exercise" (0.0.12), the first mention of the linter.
"Added a rule that checks for PMPM run exercise." (0.0.13), matching "No pnpm run exercise commands in readmes".
"Added a lint rule for empty main.ts files" (0.0.22), matching the rule that a subfolder with code needs a main.ts of more than one line.
"Added lint rule for speaker notes" (0.0.26), matching "No speaker-notes.md files".
"Support exercises with only README.md (no main.ts)" (0.2.8), matching "for stubs, a readme-only exercise is fine".
The idea underneath is a feedback loop the agent can run alone. Steps 4 and 5 of its workflow are "Run lint" and "iterate until lint passes". The agent doesn't need to judge whether the layout is right. A deterministic check tells it, the kind of check Fix the environment asks for.
A real example
The section the Skill names in its first example exists in the AI Hero cohort-002-skill-building repo. Its folder 01-retrieval-skill-building holds six exercises: 01.01-retrieval-intro, 01.02-bm25, 01.03-retrieval-with-bm25, 01.04-embeddings, 01.05-rank-fusion and 01.06-query-rewriting.
GitHub shows 01.01-retrieval-intro, 01.02-bm25 and 01.05-rank-fusion as one path down to explainer/, with the note "This path skips through empty directories". So each holds only explainer/.
01.03-retrieval-with-bm25 holds problem/ and solution/, and so do 01.04-embeddings and 01.06-query-rewriting.
01.04-embeddings is the same name the Skill's git mv example renumbers to 01.04.
The latest commit to the section, on 2025-12-09, is by mattpocock.
The real 01-retrieval-skill-building section in the AI Hero cohort-002-skill-building repo. From github.com, 30 October 2026.
01-retrieval-skill-building
01.01-retrieval-introholds only explainer/
01.02-bm25holds only explainer/
01.03-retrieval-with-bm25holds problem/ and solution/
01.04-embeddingsholds problem/ and solution/
01.05-rank-fusionholds only explainer/
01.06-query-rewritingholds problem/ and solution/
The section the Skill names in its first example
That repo's package.json runs exercises with ai-hero-cli exercise and asks for "ai-hero-cli": "^0.2.8", a version from before the lint command was removed.
Where it goes wrong
Its lint step points at a command that's gone. On 2026-07-09 Matt trimmed the CLI's internal commands, lint among them, in commit 95406cd. It deleted src/internal/lint.ts and its tests. So the lint command this Skill relies on has been gone from ai-hero-cli since 0.6.0. The changelog says so under 0.6.0: "ai-hero internal now exposes only edit-commit". The Skill at the 2026-10-29 pin commit, newer than that change, still says to run pnpm ai-hero-cli internal lint in step 4 and "iterate until lint passes" in step 5. Because misc is frozen, reports and PRs against it are closed. With a current CLI, the loop described above has no check to run. The current SKILL.md decides what the Skill does, so this Lesson still describes the lint step, and you check its rules yourself when the command is missing.
The plugin doesn't ship it. On 2026-05-11 someone reported that the four misc Skills, this one included, were missing from the plugin's list, so claude plugin install mattpocock-skills didn't register them. Matt replied: "Yep, this is intentional". Since 2026-09-04 his own install script doesn't link misc Skills into his skill folders either (pull request #1025). Matt's advice is to "install it with skills.sh".
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't):
Make a new branch, try-scaffold-exercises.
Write a short plan for teaching a new teammate your booking API:
Section 01: Booking API Basics
- 01.01 How a booking is stored
- 01.02 Create a booking (explainer + problem + solution)
The plugin doesn't ship this Skill, so install it in the project with skills.sh: npx skills@latest add mattpocock/skills --skill=scaffold-exercises.
Ask your agent to scaffold exercises from that plan.
Check its work against the rules by hand: exercises/01-booking-api-basics/01.02-create-a-booking/ should hold explainer/, problem/ and solution/, each with a readme.md that isn't empty. 01.01 should hold only explainer/.
Watch what the agent does at the lint step. Your project has no ai-hero-cli, so the command can't run. Note whether it says so or claims the layout passed.
Switch back to main and delete the branch with git branch -D try-scaffold-exercises.
Going deeper's Check questions are asked in Next up.
“Each exercise needs at least one of these subfolders: - problem/ - student workspace with TODOs - solution/ - reference implementation - explainer/ - conceptual material, no TODOs When stubbing, default to explainer/ unless the plan specifies otherwise.”
From snapshot/skills/scaffold-exercises/SKILL.md, lines 46–50: “1. Parse the plan - extract section names, exercise names, and variant types 2. Create directories - mkdir -p for each path 3. Create stub readmes - one readme.md per variant folder with a title 4. Run lint - pnpm ai-hero-cli internal lint to validate 5. Fix any errors - iterate until lint passes”
From snapshot/skills/scaffold-exercises/SKILL.md, lines 67–71: “When renumbering or moving exercises: 1. Use git mv (not mv) to rename directories - preserves git history 2. Update the numeric prefix to maintain order 3. Re-run lint after moves”
From snapshot/web/github.com/mattpocock-skills-pull-1025.md, line 16: “misc/ skills (git-guardrails-claude-code, migrate-to-shoehorn, scaffold-exercises, setup-pre-commit) were being symlinked into ~/.claude/skills and ~/.agents/skills by scripts/link-skills.sh, which only ever excluded deprecated/.”
From snapshot/skills/scaffold-exercises/SKILL.md, lines 19–25: “Each exercise needs at least one of these subfolders: - problem/ - student workspace with TODOs - solution/ - reference implementation - explainer/ - conceptual material, no TODOs When stubbing, default to explainer/ unless the plan specifies otherwise.”
