Scaffold Exercises - Course Exercise Directory Scaffolding

Skill Overview

Scaffold Exercises is used to batch-create course exercise directory structures according to a unified specification. It automatically generates exercise variants such as problem, solution, and explainer, along with README stubs, and ensures that the result passes pnpm ai-hero-cli internal lint.

Applicable Scenarios

1. Building a new course chapter from scratch: Once you have the chapter plan, create the XX-section-name/ chapter directory and all of its XX.YY-exercise-name/ exercise directories in one go, without manually running mkdir for each one.
2. Adding exercises or stubs to an existing course: Batch-generate an exercise’s explainer or problem/solution subdirectories and write minimal usable READMEs to establish the structure first, with the content to be filled in later.
3. Renumbering or moving exercises during a course revision: After adjusting the chapter order or inserting new exercises, use git mv to batch-rename directories and correct numeric prefixes, preserving the order and commit history. Run lint again after the changes to confirm everything is correct.

Core Features

1. Standardized directory naming: Chapters use XX-section-name/ under exercises/, while exercises use XX.YY-exercise-name/. The chapter number is XX, and the exercise number is XX.YY. Names consistently use lowercase dash-case to ensure uniform sorting and readability.
2. Exercise variant and README stub generation: Each exercise must create at least one of problem/ (learner workspace, containing TODOs), solution/ (reference implementation), or explainer/ (conceptual explanation without TODOs). explainer/ is generated by default. Each subdirectory receives a readme.md containing a title and description. During the stub phase, it is sufficient to create only the README without writing main.ts.
3. Lint validation and iterative fixes: After generation, run pnpm ai-hero-cli internal lint for verification. The checks cover subdirectory existence, non-empty READMEs, broken links, the absence of .gitkeep, the absence of speaker-notes.md, the absence of the pnpm run exercise command in READMEs, and the requirement that main.ts contain more than one line when code is present. If errors occur, continue adjusting until lint passes.
4. Safe renaming and moving: When adjusting exercise numbers, use git mv instead of mv to preserve Git history while maintaining directory order. Run lint again after moving to verify the result.

Frequently Asked Questions

What is Scaffold Exercises? What can it do?

It is an exercise directory scaffolding skill for the AI Hero course system. Given a chapter and exercise plan, it creates directories, generates exercise variants and README stubs, runs lint validation, and safely moves directories with git mv when renumbering is needed. It is responsible for the “structure and conventions”; the specific explanations and code implementations for the exercises still need to be written by you.

Can the generated exercise directories pass lint?

Yes. This is one of the skill’s primary goals. It includes a checklist of lint rules, and the generated structure satisfies the main constraints by default. However, if your course repository has additional rules, or if later manual changes introduce broken links or empty READMEs, errors may still occur. Fix them one by one according to the prompts, then run lint again.

What are the differences between the problem, solution, and explainer subdirectories?

problem/ is the learner workspace and contains TODOs to be completed; solution/ is the reference implementation for learners to consult; explainer/ contains purely conceptual materials and does not include TODOs. Each exercise must have at least one of these. If you are unsure which to use, default to explainer/. When an exercise includes code, each subdirectory also requires a main.ts containing more than one line.

How should I rename or renumber an existing exercise?

Use git mv to rename directories instead of mv, so Git commit history is preserved. For example, change 01.03-embeddings to 01.04-embeddings. After moving it, check that the numeric prefixes still maintain the correct order, then run lint again for verification.

Can I create only a README without writing code?

Yes. Readme-only exercises are allowed during the stub phase. The README only needs to contain real content; even a single line containing a title is sufficient to pass. Once code is actually added to the subdirectory, add a main.ts that meets the length requirement.

Why are .gitkeep and speaker-notes.md not allowed?

This is a convention of the course repository: use a README as a placeholder for empty directories instead of .gitkeep, and do not commit instructor notes alongside exercise directories. Therefore, the scaffolding process does not create either type of file, and lint will also flag them as errors.

How should I fix lint errors?

First, check which rule the error refers to: if a subdirectory is missing, add problem/, solution/, or explainer/; if a README is empty, add a title and description; if there is a broken link, correct or remove it; if .gitkeep or speaker-notes.md appears, remove it; if the README contains pnpm run exercise, rephrase it. After making the fixes, rerun pnpm ai-hero-cli internal lint until all checks pass, then commit.