Back to skills

Agent Skill

Scaffold Exercises

scaffold-exercises

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.

MattpocockToolsShell
github.com/mattpocock/skills/tree/main/skills/misc/scaffold-exercises

57K installs

•

mattpocock/skills

•

by Mattpocock

Score

8.8

/ 10

Installs

57K

Repo Stars

140.9K

Last Updated

4d ago

Fresh

Quality Ratio

97%

Description

Verified

Language

Shell

First Published

Mar 2026

Summary

The Scaffold Exercises agent skill automates the creation of structured exercise directories, complete with sections, problems, solutions, and explainers, ensuring they adhere to predefined linting standards. This skill is invaluable for educators, technical content creators, or developers who frequently build and maintain structured coding exercises or course materials, particularly for TypeScript-based projects. It is a skill with 3K installs, indicating a notable level of adoption among its users. It guides the agent to parse a structured plan and then create nested directories such as `XX-section-name/XX.YY-exercise-name/` for sections and exercises. Each exercise is further populated with variants like `problem/`, `solution/`, or `explainer/` subfolders, each containing a non-empty `readme.md`, with `main.ts` added if code is present. The skill enforces structural integrity by running `pnpm ai-hero-cli internal lint` to validate the created scaffold against rules like no broken links, also instructing to use `git mv` for any renaming operations.

Skill Definition

Create exercise directory structures that pass pnpm ai-hero-cli internal lint, then commit with git commit.

Directory naming

  • Sections: XX-section-name/ inside exercises/ (e.g., 01-retrieval-skill-building)
  • Exercises: XX.YY-exercise-name/ inside a section (e.g., 01.03-retrieval-with-bm25)
  • Section number = XX, exercise number = XX.YY
  • Names are dash-case (lowercase, hyphens)

Exercise variants

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.

Required files

Each subfolder (problem/, solution/, explainer/) needs a readme.md that:

  • Is not empty (must have real content, even a single title line works)
  • Has no broken links

When stubbing, create a minimal readme with a title and a description:

# Exercise Title

Description here

If the subfolder has code, it also needs a main.ts (>1 line). But for stubs, a readme-only exercise is fine.

Workflow

  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

Lint rules summary

The linter (pnpm ai-hero-cli internal lint) checks:

  • Each exercise has subfolders (problem/, solution/, explainer/)
  • At least one of problem/, explainer/, or explainer.1/ exists
  • readme.md exists and is non-empty in the primary subfolder
  • No .gitkeep files
  • No speaker-notes.md files
  • No broken links in readmes
  • No pnpm run exercise commands in readmes
  • main.ts required per subfolder unless it's readme-only

Moving/renaming exercises

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

Example:

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

Example: stubbing from a plan

Given a plan like:

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

Create:

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 create 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"

How to Use

Use in O-mega

Claude Code

npx skills add mattpocock/skills scaffold-exercises
Scaffold Exercises | Agent Skills | o-mega