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

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, 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 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, and no forbidden files (like .gitkeep or speaker-notes.md) exist. It also checks for broken links and ensures 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 with a title line
• main.ts (greater than one line) only when the variant contains code

The linter prohibits:

• .gitkeep files
• speaker-notes.md files
• Broken internal links
• Disallowed CLI commands

Example Workflow

Consider this input plan:

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:

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:

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 contains:

# 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 and optionally 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 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}