scaffold-exercises

Q: How do I install scaffold-exercises?

Run npx skills add https://github.com/tt-a1i/matt-skills-with-to-goal --skill scaffold-exercises in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scaffold-exercises/ (personal) or .claude/skills/scaffold-exercises/ (project).

by tt-a1iEducation & Science

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.

Installs: 96
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/tt-a1i/matt-skills-with-to-goal --skill scaffold-exercises

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads scaffold-exercises automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Parse the plan - extract section names, exercise names, and variant types
Create directories - mkdir -p for each path
Create stub readmes - one readme.md per variant folder with a title
Run lint - pnpm ai-hero-cli internal lint to validate
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:

Use git mv (not mv) to rename directories - preserves git history
Update the numeric prefix to maintain order
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"

FAQ

What does the scaffold-exercises skill do?

How do I install scaffold-exercises?

Run npx skills add https://github.com/tt-a1i/matt-skills-with-to-goal --skill scaffold-exercises in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scaffold-exercises/ (personal) or .claude/skills/scaffold-exercises/ (project).

Which AI agents can use scaffold-exercises?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is scaffold-exercises safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains scaffold-exercises?

It is published by tt-a1i in tt-a1i/matt-skills-with-to-goal. It has 96 recorded installs.