--- name: mattpocock-scaffold-exercises description: "Scaffold course exercises." license: MIT metadata: source: mattpocock/skills source-commit: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d upstream-name: scaffold-exercises upstream-status: published adaptation: namespaced-port --- ## Skillz integration This is Matt Pocock's version. Skill references use the `mattpocock-` prefix. Read a referenced skill's `SKILL.md` through the host's skill loader or file tools. Map AskUserQuestion to the host's question tool and shell examples to its shell. Use delegation only when available and permitted by the active instructions; otherwise perform the same work sequentially and report that limit. The user's scope and repository rules govern setup, file writes, tracker changes, messages, schedules, publishing, merging, and cleanup. A skill invocation alone does not broaden the user's request. Preserve existing work and configuration. Verify provider examples against current primary documentation before use. # 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" ```