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

> Easily add a new lesson to the ai-engineering-from-scratch curriculum using scaffold-lesson.sh. This script creates a standardized directory structure and starter files for your new lesson.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** – Generated from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scaffold-lesson.sh), complete the lesson by editing the generated files:

1. **Edit [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py)** – Replace the `NotImplementedError` stub with the lesson’s actual implementation logic.
3. **Update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) changes together.

## Summary

- **Location**: The scaffolding script is [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) to add pedagogical content, implement the logic in [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py), add a corresponding entry to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and commit all changes as a single atomic commit. The script prints these exact next steps upon completion.