# How the scaffold-exercises Skill Creates Learning Exercise Structures in mattpocock/skills

> Learn how mattpocock/skills scaffold-exercises transforms lesson plans into structured learning exercises. It parses metadata, auto-generates files, and enforces naming conventions.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: how-to-guide
- Published: 2026-04-04

---

**The scaffold-exercises skill transforms a textual lesson plan into a fully-scaffolded directory hierarchy by parsing section metadata, enforcing zero-padded dash-case naming conventions, and auto-generating required stub files before running a strict internal linter.**

The scaffold-exercises skill is a declarative automation tool within the mattpocock/skills repository that eliminates manual boilerplate when building educational content. It consumes a high-level outline of sections and exercises, then deterministically generates a lint-compliant folder structure ready for content authoring. This skill ensures every exercise variant contains the mandatory files required by the AI Hero CLI toolchain.

## The Five-Step Generation Pipeline

According to [`scaffold-exercises/SKILL.md`](https://github.com/mattpocock/skills/blob/main/scaffold-exercises/SKILL.md), the skill executes a deterministic workflow that bridges the gap between a content outline and a valid exercise repository.

### Parse the High-Level Plan

First, the skill extracts structured data from the user-provided text. It identifies section numbers and names, exercise numbers and names, and the requested exercise variants (problem, solution, explainer). This parsing step is defined in workflow step 1 of the skill definition.

### Create the Directory Tree

Using `mkdir -p`, the skill builds a nested hierarchy under `exercises/`. It enforces strict naming conventions: sections become `XX-section-name/` and exercises become `XX.YY-exercise-name/`, where numbers are zero-padded and names use dash-case. For example, section 5 becomes `05-memory-skill-building/` and exercise 5.2 becomes `05.02-short-term-memory/`.

### Populate Variant Folders

For each requested variant—`problem/`, `solution/`, or `explainer/`—the skill generates a minimal [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md) containing a title line and short description. This satisfies the "non-empty" requirement for every variant folder. The stub generation is described in workflow steps 3 and 4.

### Execute the Internal Linter

The skill runs `pnpm ai-hero-cli internal lint` to validate the scaffold. The linter verifies that each exercise contains at least one variant folder, each variant contains a non-empty [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md), and no forbidden files (like `.gitkeep` or [`speaker-notes.md`](https://github.com/mattpocock/skills/blob/main/speaker-notes.md)) exist. It also checks for broken links and ensures [`main.ts`](https://github.com/mattpocock/skills/blob/main/main.ts) exists when code files are expected.

### Auto-Correct Until Pass

Any violations reported by the linter trigger automatic corrections. The skill adds missing readmes, removes disallowed files, and adjusts the structure until the lint check passes, as specified in workflow step 5.

## Naming Conventions and Directory Structure

The scaffold enforces a predictable, sortable filesystem layout. Sections use the pattern `XX-section-name/` and exercises use `XX.YY-exercise-name/`, ensuring alphabetical sorting matches logical ordering. Variants are created as subdirectories within each exercise folder.

## Required Files and Validation Rules

Every variant folder must contain:

- A non-empty [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md) with a title line
- [`main.ts`](https://github.com/mattpocock/skills/blob/main/main.ts) (greater than one line) only when the variant contains code

The linter prohibits:

- `.gitkeep` files
- [`speaker-notes.md`](https://github.com/mattpocock/skills/blob/main/speaker-notes.md) files
- Broken internal links
- Disallowed CLI commands

## Example Workflow

Consider this input plan:

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

```

The skill generates these commands:

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

```

Resulting in this structure:

```text
exercises/
└─ 05-memory-skill-building/
   ├─ 05.01-introduction-to-memory/
   │  └─ explainer/
   │     └─ readme.md
   ├─ 05.02-short-term-memory/
   │  ├─ explainer/
   │  │  └─ readme.md
   │  ├─ problem/
   │  │  └─ readme.md
   │  └─ solution/
   │     └─ readme.md
   └─ 05.03-long-term-memory/
      └─ explainer/
         └─ readme.md

```

Each [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md) contains:

```markdown

# Short-term Memory

Description here

```

## Summary

- The scaffold-exercises skill parses textual lesson plans to extract section and exercise metadata.
- It enforces zero-padded dash-case naming conventions for sortable directory structures.
- Every exercise variant must contain a non-empty [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md) and optionally [`main.ts`](https://github.com/mattpocock/skills/blob/main/main.ts) for code.
- The `pnpm ai-hero-cli internal lint` command validates the scaffold against strict rules.
- Violations are auto-corrected iteratively until the structure passes linting.

## Frequently Asked Questions

### What file naming convention does the scaffold-exercises skill use?

The skill enforces zero-padded numbers with dash-case names. Sections follow the pattern `XX-section-name/` and exercises follow `XX.YY-exercise-name/`, ensuring directories sort chronologically. This convention is hardcoded in the skill's directory creation logic.

### What variants can an exercise contain?

An exercise must contain at least one of three variant folders: `problem/`, `solution/`, or `explainer/`. These variants represent different stages of the learning process. The skill generates all requested variants simultaneously based on the input plan.

### Why does every variant folder require a readme.md?

The internal linter mandates a non-empty [`readme.md`](https://github.com/mattpocock/skills/blob/main/readme.md) in every variant folder to ensure content authors provide context for each exercise stage. The skill auto-generates these stubs with a title line during scaffolding to satisfy this requirement immediately.

### How do I invoke the scaffold-exercises skill?

Install and run the skill using the Skills CLI:

```bash
npx skills@latest add mattpocock/skills/scaffold-exercises

```

The skill will then prompt you for a lesson plan and execute the full scaffolding pipeline automatically.