How to use the Scaffold Exercises agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. The agent reads those instructions and follows them, so you do not have to explain the same workflow in every conversation.

The scaffold-exercises skill covers one narrow job. Given a plan for a course section, the agent creates the directories, writes stub readme.md files, runs the lint command, fixes any errors it reports, and commits the result with git. The skill only creates stubs and placeholder readmes; it does not write the actual exercise content.

• Sections are named XX-section-name inside exercises/, for example 01-retrieval-skill-building.
• Exercises are named XX.YY-exercise-name inside a section, for example 01.03-retrieval-with-bm25.
• Each exercise gets at least one of problem/, solution/ or explainer/. When the plan does not say otherwise, the skill defaults to explainer/.
• Names are dash-case: lowercase letters with hyphens.

How do you install the scaffold-exercises skill?

You can install the skill in either of two ways. Download the ZIP file from this page and unzip it into one of the locations below. Alternatively, upload the skill in the Claude apps.

For a personal install that applies across your projects, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there.

In the Claude apps, go to Settings → Capabilities → Skills and upload the skill from there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description tells the agent when to use it: when you want to scaffold exercises, create exercise stubs, or set up a new course section. Describe the structure you want in ordinary words and include the plan if you have one.

Clear plans work best. Give the section number and name, each exercise with its number and name, and which variants each exercise needs. If you leave out the variants, the skill uses explainer/.

• Scaffold a new section called 05 Memory Skill Building with three exercises from this plan.
• Create exercise stubs for section 03 from the outline I paste below.
• Set up a new course section for retrieval and add placeholder readmes for each exercise.

What does a stubbing example look like?

Suppose the plan is a section numbered 05 called Memory Skill Building, with three exercises. Exercise 05.02 needs explainer, problem and solution variants, and the other two need only the default explainer. The skill turns this into directories and readme stubs.

Each readme stub is a title line, since a single title is enough for the lint check to pass. After the stubs exist, the agent runs the lint command and iterates until it passes, then commits the work.

• Directories are created with mkdir -p, one per exercise variant.
• Each variant folder gets a readme.md containing a title such as # Short-term Memory.
• The lint command is run and any errors are fixed before committing.

How do you rename or move exercises safely?

When you renumber or move exercises, the skill tells the agent to use git mv instead of mv. This keeps the git history attached to the renamed folder. After any move, the numeric prefix should be updated to keep the order correct, and lint should be run again.

The example below renames exercise 01.03 to 01.04 inside section 01.

• Use git mv for every rename or move.
• Update the numeric prefix so the order stays correct.
• Re-run the lint command after the moves.

What does the lint check require?

The skill is built around the linter run by pnpm ai-hero-cli internal lint. Knowing its main rules helps you understand errors when they appear. The agent should fix errors it reports rather than work around them.

• Each exercise has subfolders such as problem/, solution/ and 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 and no speaker-notes.md files.
• No broken links in readmes.
• No pnpm run exercise commands in readmes.
• main.ts is required per subfolder unless the subfolder is readme-only.

What do you need before using it, and what are the safety notes?

The skill needs Node.js and pnpm, the ai-hero-cli tool with its internal lint command, and Git. Without the lint command the workflow cannot complete, and the agent would fail or improvise. The skill runs scripts. It does not use the network.

Because the skill runs scripts, read the SKILL.md and the files in the skill folder before installing a skill from anywhere. Review the commands the agent proposes, especially git commands that change history, and check the diff before you accept a commit.

• Requires Node.js and pnpm, the ai-hero-cli tool, and Git.
• Runs scripts: yes.
• Uses network: no.
• The skill's files are agents/openai.yaml and SKILL.md.

What tips help the skill work well?

Keep your plan in one place so the agent sees the full structure at once. Use the same naming pattern you already have in the repository, because the skill uses dash-case and fixed number prefixes. Review the generated stubs before writing real content, since the readmes contain only titles.

• Paste the full plan rather than describing sections one at a time.
• Decide the variants up front, because the default is explainer/ only.
• Check the lint output yourself if the agent reports success too quickly.
• Fill in the placeholder readmes only after the structure passes lint.