# How to Add a New Lesson to the AI Engineering from Scratch Curriculum

> Learn how to add a new lesson to the AI Engineering from Scratch curriculum. Follow simple steps to create folders, write documentation, and register your lesson, enhancing the course content.

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

---

**Add a new lesson by creating a numbered folder under `phases/` with `code/`, `docs/`, and `outputs/` subdirectories, writing a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file following the standard template from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md), and registering the lesson in the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) navigation tables before submitting a single-commit pull request.**

The AI Engineering from Scratch curriculum is organized as a collection of modular lessons within the `rohitg00/ai-engineering-from-scratch` repository. To add a new lesson to this curriculum, contributors must follow a strict folder naming convention, documentation format, and registration process that integrates with the automated site generator at [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js).

## Prerequisites and Key Files

Before adding a new lesson, review the following authoritative resources in the repository:

- **[`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md)**: The primary contribution guide describing folder layout, commit conventions, and the pull request workflow.
- **[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)**: The scaffold file containing the required folder hierarchy, documentation skeleton, and output formats (lines 7–21).
- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)**: Contains the phase-wise lesson tables that power the website navigation.
- **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)**: Tracks lesson status glyphs (`✅`, `🚧`, `⬚`) and drives the CI integrity checks.
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Parses the markdown tables to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), the website's source of truth.

## Step-by-Step Implementation

### Scaffold the Lesson Directory

Every lesson lives in a path following the pattern `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`. For example, lesson 23 in Phase 3 would reside at `phases/03-deep-learning-core/23-my-new-lesson/`.

Create the mandatory subdirectories:

- **`code/`**: Runnable implementations (Python, TypeScript, Rust, Julia).
- **`docs/`**: Narrative documentation containing the required [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) file.
- **`outputs/`**: Optional prompts, skills, agents, or MCP servers produced by the lesson.

```bash
mkdir -p phases/03-deep-learning-core/23-my-new-lesson/{code,docs,outputs}

```

### Write the Documentation File

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must begin with a standardized front-matter block as defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25–34):

```markdown

# My New Lesson Title

> One-line motto that captures the core idea.

**Type:** Build
**Languages:** Python, TypeScript
**Prerequisites:** [Previous lesson link]
**Time:** ~30 minutes

```

Following the front matter, the document must follow the six-beat narrative structure: **Problem → Concept → Build It → Use It → Ship It → Exercises** (see the template lines 35–80). Copy the template to your lesson folder and replace the placeholder content:

```bash
cp LESSON_TEMPLATE.md phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

```

### Update Navigation Tables

The curriculum UI discovers lessons through markdown tables in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md). You must update both files to register the new lesson:

1. **Append a row to the appropriate phase table** in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md):

```markdown
| 23 | [My New Lesson](phases/03-deep-learning-core/23-my-new-lesson/) | Build | Python |

```

2. **Add a matching entry** to the phase’s section in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), preserving the status glyph (`⬚` for work-in-progress):

```markdown
⬚ 23  My New Lesson

```

Both files are parsed by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) (described in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) lines 8–11). After editing, run the generator locally to verify that only a timestamp change appears in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js).

### Commit and Submit

The repository enforces a strict **one commit per lesson** policy. Use a conventional commit title following the format `feat(phase-<NN>/<MM>): add <lesson-slug>`:

```bash
git add phases/03-deep-learning-core/23-my-new-lesson README.md ROADMAP.md
git commit -m "feat(phase-03/23): add my-new-lesson"

```

The CI pipeline will automatically regenerate the site data and enforce [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)/[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) integrity. Ensure you have run unit tests for your code before pushing:

```bash
python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code

```

## Complete Working Example

Below is a minimal shell script demonstrating the full workflow to add a lesson to Phase 3:

```bash

# 1️⃣ Clone and branch

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
git checkout -b add-lesson-phase3-23-my-new-lesson

# 2️⃣ Scaffold folders

mkdir -p phases/03-deep-learning-core/23-my-new-lesson/{code,docs,outputs}
cp LESSON_TEMPLATE.md phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

# 3️⃣ Create a runnable implementation

cat > phases/03-deep-learning-core/23-my-new-lesson/code/main.py <<'PY'
def demo():
    print("Hello from my new lesson")

if __name__ == "__main__":
    demo()
PY

# 4️⃣ Edit docs/en.md with your $EDITOR (follow the six-beat structure)

# 5️⃣ Update README.md table (add row under Phase 3)

# | 23 | [My New Lesson](phases/03-deep-learning-core/23-my-new-lesson/) | Build | Python |

# 6️⃣ Update ROADMAP.md (add under Phase 3 section)

# ⬚ 23  My New Lesson

# 7️⃣ Test and commit

python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code
git add phases/03-deep-learning-core/23-my-new-lesson README.md ROADMAP.md
git commit -m "feat(phase-03/23): add my-new-lesson"
git push origin add-lesson-phase3-23-my-new-lesson

# 8️⃣ Open PR (using GitHub CLI)

gh pr create --title "feat(phase-03/23): add my-new-lesson" \
    --body "Adds a new lesson to Phase 3 on building X from scratch."

```

## Summary

- **Lesson location**: Create folders at `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with `code/`, `docs/`, and `outputs/` subdirectories.
- **Documentation**: Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the front-matter template from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) and the six-beat structure.
- **Registration**: Add rows to both [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) for the site generator at [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to discover the lesson.
- **Submission**: Commit exactly one change per lesson using conventional commit format `feat(phase-XX/YY): add lesson-name`.

## Frequently Asked Questions

### What is the required folder naming convention for new lessons?

Lessons must follow the path `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `<NN>` is the two-digit phase number and `<MM>` is the two-digit lesson number. For example, `phases/03-deep-learning-core/23-my-new-lesson/` places lesson 23 in Phase 3.

### How do I register a new lesson so it appears on the website?

You must manually update two files: add a row to the phase table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and add an entry with a status glyph (`⬚`, `🚧`, or `✅`) to [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md). The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses these tables to generate the navigation data.

### Can I add multiple lessons in a single pull request?

No. The repository enforces a strict **one commit per lesson** policy. Each lesson must be a single, atomic commit with a conventional title like `feat(phase-03/23): add my-new-lesson`.

### What content structure must the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file follow?

The documentation must start with the standard front-matter block (Title, Type, Languages, Prerequisites, Time) followed by a six-beat narrative: **Problem → Concept → Build It → Use It → Ship It → Exercises**. This template is defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) lines 25–80.