scaffold-exercises

Overview of scaffold-exercises skill

The scaffold-exercises skill helps an agent create exercise folder structures that match a strict training-content convention: numbered sections, numbered exercises, variant subfolders like problem/, solution/, and explainer/, plus minimal files that are valid enough to pass lint-oriented checks. If you are building course material, workshop exercises, or a structured learning repo, this is the real job it solves.

What scaffold-exercises is best for

Use scaffold-exercises when you already know the learning plan and need the filesystem scaffold created correctly, fast, and consistently. It is best for:

• setting up a new course section under exercises/
• creating multiple exercise stubs from a curriculum outline
• adding problem, solution, or explainer variants without guessing naming rules
• avoiding broken starter directories that later fail repo linting

Who should install scaffold-exercises

The best-fit user is someone working in a repo that already has an exercise-based teaching structure. The scaffold-exercises skill is especially useful for maintainers, curriculum authors, and AI-assisted repo editors who need correct paths and file placeholders more than prose generation.

What makes scaffold-exercises different from a generic prompt

A normal prompt can tell an AI to “make some exercise folders,” but scaffold-exercises adds repository-specific discipline:

• section folders use XX-section-name
• exercise folders use XX.YY-exercise-name
• names are dash-case
• each exercise needs at least one variant folder
• each variant needs a non-empty readme.md
• code files like main.ts are only needed when code actually exists

That means fewer malformed paths, fewer empty placeholders, and less cleanup after generation.

The main adoption question to answer first

Install scaffold-exercises if your biggest risk is structure drift, not content originality. This skill is about scaffolding that conforms to conventions. It is not a full curriculum planner, lesson writer, or code generator on its own.

How to Use scaffold-exercises skill

How scaffold-exercises install typically works

The repository excerpt does not publish its own custom installer inside SKILL.md, so usage depends on your skills runtime. In Skills-based setups, teams commonly add the source repo and then invoke the scaffold-exercises skill by name. If your environment supports it, a common pattern is:

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

If your agent platform loads skills another way, point it at the mattpocock/skills repository and select scaffold-exercises.

Read this file first before using scaffold-exercises

Start with:

• scaffold-exercises/SKILL.md

This skill is simple and self-contained. There are no extra rules/, resources/, or helper scripts surfaced in the repository preview, so most of the useful behavior is encoded directly in that one file.

What input scaffold-exercises needs from you

The skill works best when you provide a plan with four things:

1. the section number and title
2. the exercise numbers and titles
3. which variants each exercise should include
4. whether you want stubs only or real starter code

Without that, the agent can still scaffold, but it will make defaults you may not want, especially around explainer/ versus problem/.

The minimum prompt that works

A rough but workable scaffold-exercises usage prompt looks like this:

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

This is enough because it supplies numbering, names, location, and variant types.

A stronger prompt that improves output quality

A better prompt makes defaults explicit:

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

Why this works better:

• it removes ambiguity around folder variants
• it prevents unnecessary code files
• it preserves naming conventions up front
• it tells the agent what “non-empty” should mean in practice

Default behavior to expect when the plan is incomplete

One of the most important details in the upstream skill: when stubbing, the default is explainer/ unless the plan says otherwise. That is useful for conceptual exercises, but it can be wrong if you actually need student workspaces. If you want hands-on tasks, say problem/ explicitly.

What scaffold-exercises will create

The skill is oriented around a repeatable directory pattern such as:

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

For stub scaffolds, readme-only folders are acceptable. If you later add code, then main.ts should be present and contain more than a trivial one-line placeholder.

Practical workflow for using scaffold-exercises in a real repo

A good workflow is:

1. Draft the curriculum outline in plain English.
2. Convert it into numbered section and exercise names.
3. Specify variants per exercise.
4. Ask the agent to run scaffold-exercises.
5. Review path names before adding content.
6. Run your repo lint or validation step.
7. Only then fill in code and fuller docs.

This order matters because the skill is best at structure first.

Naming mistakes that cause the most rework

The most common bad inputs are:

• missing numeric prefixes
• using spaces instead of dash-case
• confusing section numbering with exercise numbering
• omitting whether folders should be problem, solution, or explainer

If your plan says “Create an exercise on BM25,” the agent still has to invent too much. If your plan says “Create 01.03-retrieval-with-bm25 inside 01-retrieval-skill-building with problem/ and solution/,” the result is usually reliable.

Fit guidance for scaffold-exercises for Skill Scaffolding

scaffold-exercises for Skill Scaffolding is a good fit when your bottleneck is repo shape and consistency. It is a weak fit when you need rich pedagogy, assessments, or polished explanations generated automatically. Treat it as a structure enforcer, not a substitute for instructional design.

scaffold-exercises skill FAQ

Is scaffold-exercises beginner-friendly

Yes, if you already understand the exercise structure you want. The skill itself is simple: it mainly enforces naming, folder layout, and minimal required files. The harder part is deciding your curriculum and variant choices beforehand.

When should I not use scaffold-exercises

Skip scaffold-exercises if:

• your repo does not use numbered section and exercise folders
• you only need a single markdown lesson, not an exercise tree
• you want the AI to invent the course architecture from scratch
• your project uses a different file contract than readme.md plus optional main.ts

How is scaffold-exercises different from manually creating folders

Manual scaffolding is fine for one exercise. The value of scaffold-exercises usage shows up when you create many exercises and need consistency. It reduces the chance of invalid names, empty readmes, and mixed folder conventions that break downstream checks.

Does scaffold-exercises generate the full exercise content

No. Its core value is scaffolding. It can create minimal readmes and placeholder structure, but you should not treat it as a full lesson-authoring system.

Do I need problem, solution, and explainer every time

No. The upstream rules only require at least one of them. For stubs, explainer/ is the default if nothing else is specified. Choose variants based on the exercise goal, not out of habit.

Is scaffold-exercises tied to one repo layout

It is opinionated. The skill assumes an exercises/ hierarchy and specific numbering conventions. If your repo follows that pattern, it is useful. If not, you will spend time fighting its assumptions.

How to Improve scaffold-exercises skill

Give scaffold-exercises a numbered plan, not a topic list

The fastest way to get better results from scaffold-exercises is to stop prompting with themes and start prompting with exact target paths. Compare:

Weak:

• “Add some exercises about retrieval.”

Strong:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

The second prompt gives the agent almost no room to misname folders.

Specify variant intent instead of letting defaults decide

If you omit variant types, the skill may choose explainer/ for stubs. That is efficient, but it may not match your teaching design. Say:

• use problem/ for student tasks
• use solution/ for references
• use explainer/ for concept-only material

That single clarification materially improves scaffold quality.

Ask for minimal but valid readmes

A common failure mode is placeholders that are technically created but not useful. Tell the agent to put a title and one-sentence description into every readme.md. That keeps files non-empty and makes later authoring easier.

Prevent unnecessary code files

Another common mistake is generating main.ts everywhere. The upstream skill does not require that for readme-only stubs. If you want a lightweight scaffold, say “readme-only unless code is explicitly needed.” This keeps the first pass cleaner.

Validate names before generating many exercises

For large batches, ask the agent to first list the proposed paths, then create them after approval. This catches numbering collisions and awkward slugs before you end up renaming dozens of folders.

Iterate after the first scaffold-exercises pass

After the first run, improve results by reviewing:

• numbering continuity
• variant completeness
• readme usefulness
• whether each exercise belongs in the chosen section

Then ask the agent for a second pass focused only on corrections. scaffold-exercises guide quality improves noticeably when generation and review are separated.

Where scaffold-exercises still needs human judgment

The scaffold-exercises skill cannot decide the right teaching sequence, exercise difficulty, or pedagogical coverage for you. The best results come when you use it to automate structure and keep human review for curriculum logic.