How to Add a New Lesson Using scaffold-lesson.sh

You can add a new lesson to the ai-engineering-from-scratch curriculum by running scripts/scaffold-lesson.sh <phase-directory> <lesson-slug> "<lesson-title>" from the repository root, which automatically validates inputs, creates the standardized directory structure, and generates starter files.

The scaffold-lesson.sh script lives in the rohitg00/ai-engineering-from-scratch repository and automates the creation of lesson skeletons inside the phases hierarchy. When you add a new lesson using scaffold-lesson.sh, the tool enforces the repository’s structural conventions—such as the NN-kebab-case slug format and mandatory subdirectories—ensuring compatibility with downstream CI checks and curriculum generation pipelines.

How scaffold-lesson.sh Works

Located at scripts/scaffold-lesson.sh, the helper script performs eight distinct operations to bootstrap a lesson. Each step includes guards to prevent common setup errors.

Input Validation and Guards

The script first validates that you are running from the repository root and have supplied the minimum required arguments (phase directory and lesson slug). According to lines 4–9 and 22–26 of scripts/scaffold-lesson.sh, it aborts with a clear error if invoked incorrectly or from the wrong directory.

Next, it checks that the target phase directory exists and that the requested lesson slug is not already present (lines 31–40). This prevents accidental overwrites of existing content.

Finally, the script validates the lesson slug against the NN-kebab-case convention (e.g., 03-tokenizers) on lines 42–45. The numeric prefix ensures proper sorting within the curriculum.

Directory Structure Creation

Once validation passes, the script creates the four mandatory subdirectories for every lesson (lines 47–48):

• code/ – for implementation files
• notebook/ – for Jupyter notebooks
• docs/ – for documentation
• outputs/ – for generated artifacts

Starter File Generation

The script populates these directories with boilerplate:

• docs/en.md – Generated from LESSON_TEMPLATE.md (lines 57–66), this file includes pre-filled front-matter (type, languages, prerequisites, time estimate) and placeholder sections for problem description, concept, build steps, and exercises.
• code/main.py – A stub Python file containing a NotImplementedError (lines 18–25), prompting you to implement the lesson’s core logic.
• .gitkeep – Empty placeholder files added to notebook/ and outputs/ (lines 27–28) so Git tracks these directories even when empty.

Next-Steps Output

After file creation, the script prints a checklist (lines 30–38) instructing you to edit the generated markdown, implement the code, add a row to ROADMAP.md, and commit the changes atomically.

Step-by-Step: Adding a New Lesson

The following workflow demonstrates scaffolding a lesson titled "Tokenizers from Scratch" inside Phase 05.

Run the script from the repository root:

scripts/scaffold-lesson.sh 05-nlp-foundations-to-advanced 03-tokenizers "Tokenizers from Scratch"

The script outputs confirmation and next steps:

created phases/05-nlp-foundations-to-advanced/03-tokenizers/

next:
  1. edit phases/05-nlp-foundations-to-advanced/03-tokenizers/docs/en.md
  2. write phases/05-nlp-foundations-to-advanced/03-tokenizers/code/main.py
  3. add a markdown-link row to ROADMAP.md under Phase 05:
     | 03 | [Tokenizers from Scratch](phases/05-nlp-foundations-to-advanced/03-tokenizers) | ✅ | ~75 min |
  4. atomic commit: git add phases/05-nlp-foundations-to-advanced/03-tokenizers ROADMAP.md && git commit -m "feat(phase-05/03): Tokenizers from Scratch"

Post-Scaffolding Workflow

After running scaffold-lesson.sh, complete the lesson by editing the generated files:

1. Edit docs/en.md – Fill in the problem statement, concept explanation, step-by-step build instructions, usage examples, shipping checklist, exercises, key terms, and further reading sections.
2. Implement code/main.py – Replace the NotImplementedError stub with the lesson’s actual implementation logic.
3. Update ROADMAP.md – Add a new row linking to your lesson under the appropriate phase, following the existing table format.
4. Commit atomically – The repository follows a "one-commit-per-lesson" rule. Stage the new directory and ROADMAP.md changes together.

Summary

• Location: The scaffolding script is scripts/scaffold-lesson.sh in the rohitg00/ai-engineering-from-scratch repository.
• Requirements: You must run the script from the repository root, specify an existing phase directory, and use the NN-kebab-case slug format.
• Output: The script creates code/, notebook/, docs/, and outputs/ directories, plus starter files for documentation and implementation.
• Integration: Generated lessons automatically adhere to the structural conventions required by the repository’s CI and curriculum generation pipelines.

Frequently Asked Questions

What happens if I run scaffold-lesson.sh from outside the repository root?

The script contains a guard clause (lines 4–9) that detects the current working directory and aborts with an error message if you are not at the repository root. This ensures relative paths resolve correctly to the phases/ directory.

What is the required format for the lesson slug?

The slug must follow the NN-kebab-case convention, where NN is a two-digit number (e.g., 03-tokenizers, 12-transformers). The script validates this pattern on lines 42–45 of scripts/scaffold-lesson.sh to maintain consistent lesson ordering.

Do I need to manually create the phase directory before running the script?

Yes. The script checks that the specified phase directory already exists (lines 31–40) and aborts if it cannot find it. You must create the phase folder first or choose an existing one from the phases/ hierarchy.

How do I complete the lesson after scaffolding?

After running the script, edit docs/en.md to add pedagogical content, implement the logic in code/main.py, add a corresponding entry to ROADMAP.md, and commit all changes as a single atomic commit. The script prints these exact next steps upon completion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}