Index of every page on this site: llms.txt
All skills
mattpocock avatar

/scaffold-exercises

@abeeaf9 official
by Matt Pocockmattpocock/skills329k stars
27,654
Run it yourself

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

Use this Skill: https://skilld.dev/gh/mattpocock/skills/scaffold-exercises

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈56 tokens for metadata: the name and description. ≈834 when used: this file. ≈27 more on demand in 1 file.

Description uses 2.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈225 characters, or 2.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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

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:

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"

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is safe for its intended purpose of scaffolding course exercises. It contains a minor risk of indirect prompt injection as it generates file structures based on user-provided plans, though specific formatting rules and internal linting provide some protection.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at abeeaf9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 7 months ago
  • Git/VCS
  • exercises
  • scaffolding
  • course-content
  • directory-structure
  • linting
  • pnpm

README badge

README badge for mattpocock/skills/scaffold-exercises

Creates exercise directory structures with numbered sections, problems, solutions, and explainers that pass the ai-hero-cli linter. Use when scaffolding course materials or exercise stubs that follow dash-case naming and require non-empty readme.md files in each variant folder.

Generated from the current SKILL.md.

What directory structure does this skill create?
Sections as `XX-section-name/` folders, exercises as `XX.YY-exercise-name/` subfolders inside sections, with variant subfolders like `problem/`, `solution/`, and `explainer/` for each exercise.
Do I need to create all three variants (problem, solution, explainer) for each exercise?
No. Each exercise needs at least one of `problem/`, `solution/`, or `explainer/`. When stubbing, the skill defaults to `explainer/` unless the plan specifies otherwise.
What files are required in each variant folder?
A non-empty `readme.md` is mandatory. If the folder contains code, a `main.ts` file (more than 1 line) is also required, but readme-only exercises are acceptable for stubs.
Does the skill validate my structure after creation?
Yes. After creating directories and stubs, run `pnpm ai-hero-cli internal lint` to validate against rules like non-empty readmes, no broken links, and proper folder structure.
How do I rename or renumber exercises?
Use `git mv` instead of `mv` to preserve git history, update the numeric prefix, and re-run lint after the move.

Generated from the current SKILL.md. These answers refresh after source changes.