scaffold-exercises

Original：🇺🇸 English
Translated

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.

4installs
Sourcemattpocock/skills
Added on

NPX Install

npx skill4agent add mattpocock/skills scaffold-exercises

Tags

Translated version includes tags in frontmatter
exercise-scaffoldingdirectory-structurelint-validationgit-workflowcourse-exercises

SKILL.md Content

View Translation Comparison →

Scaffold Exercises

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:
md
# 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:
bash
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:
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
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"