scaffold-exercises

Overview of scaffold-exercises skill

scaffold-exercises is a setup-oriented skill for creating exercise directories that match the repository’s naming and linting expectations. It is most useful when you need to add a new section, create exercise stubs, or standardize problem/solution/explainer layouts without guessing the folder structure. The real job is not just “make folders” but “produce a valid exercise scaffold that is ready for content, review, and pnpm ai-hero-cli internal lint.”

What scaffold-exercises is for

Use the scaffold-exercises skill when you already know the learning content you want to add, but need a clean directory skeleton to hold it. It is a good fit for course authors, maintainers, and agents that must create repeatable exercise structures across multiple sections.

Where it helps most

The skill is strongest when the repository has strict conventions: numbered sections, numbered exercises, and required readme.md files inside each variant folder. The scaffold-exercises install is especially valuable if your workflow includes frequent stubbing, because it reduces formatting errors before content is written.

What it expects from you

This skill assumes you can provide a section number, exercise number, exercise name, and the intended variant type. If your brief is vague, the scaffold can still be built, but the result is better when the input clearly distinguishes problem, solution, and explainer use cases.

How to Use scaffold-exercises skill

Install scaffold-exercises

Install the scaffold-exercises skill with:

npx skills add mattpocock/skills --skill scaffold-exercises

That is the practical scaffold-exercises install path used in the repo. Once installed, use it as a directory-creation workflow, not as a generic writing prompt.

Give the skill a structured brief

The best scaffold-exercises usage starts with a compact plan that names the target section, the exercise, and the desired variant. For example: “Create exercises/02-generation/02.01-rerank-basics/ with explainer/ and solution/ stubs; keep naming dash-case; ensure each readme has content.” That is much better than “scaffold a lesson,” because it tells the skill what paths to build and what files must exist.

Read the right files first

Start with SKILL.md, then inspect the repository’s exercise conventions around section naming, required subfolders, and stub content. If the repo adds adjacent guidance elsewhere, read those files before generating anything. For scaffold-exercises, the key decision points are the directory format, the default variant, and whether code files are needed or a readme-only stub is enough.

Follow the repo’s minimal-valid pattern

A safe scaffold-exercises guide is to create directories first, then add non-empty readme.md files, then add main.ts only when the variant actually contains code. If you are stubbing, defaulting to explainer/ is usually cleaner than inventing problem files that imply unfinished student work. Keep titles aligned with the exercise name and avoid broken links in first-pass placeholders.

scaffold-exercises skill FAQ

Is scaffold-exercises only for new exercises?

No. The scaffold-exercises skill also helps when you are adding a new section or standardizing an existing series of exercises. It is useful any time you need the repo’s exercise structure to be valid before deeper content is written.

Do I need to use the skill instead of a normal prompt?

Use the skill when structure matters more than prose. A normal prompt can describe the idea, but scaffold-exercises is better when the output must obey naming rules, required folders, and lint-friendly stubs.

Is scaffold-exercises beginner friendly?

Yes, if you can identify the exercise name and target folder. The main beginner mistake is under-specifying the variant type or ignoring the section/exercise numbering scheme, which can produce paths that look plausible but do not fit the repo.

When should I not use scaffold-exercises?

Do not use scaffold-exercises if you only need lesson copy, brainstorming, or a one-off markdown draft with no directory constraints. It is a repository-structure skill, not a content-generation shortcut.

How to Improve scaffold-exercises skill

Give more exact paths and variant intent

The biggest quality boost comes from specifying the exact directory and the role of each subfolder. A strong request says what should exist, for example: “Create exercises/03-ranking/03.02-bm25-tuning/ with problem/, solution/, and explainer/ readmes; the problem/ folder should include TODOs, the solution/ folder should include the reference outline, and explainer/ should stay conceptual.” That helps the scaffold-exercises skill make the right structure on the first pass.

Watch the common failure modes

The most common issues are wrong numbering, missing readme.md, empty placeholders, and adding code files when a stub-only exercise would be enough. Another frequent mistake is mixing section-level and exercise-level names in the same path. The scaffold-exercises guide works best when you keep naming conventions and content expectations separate.

Iterate after the first scaffold

After generation, verify that each folder contains the required files and that the wording in each readme matches the actual exercise type. If you later decide the exercise needs code, add main.ts only where it changes the learning experience. For scaffold-exercises, the fastest improvement loop is: scaffold, lint, adjust names, then expand content.