# 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 structure your lesson, write documentation, and update navigation.

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

---

**Create a folder under `phases/` with `code/`, `docs/`, and `outputs/` subdirectories, write the documentation in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the template from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md), and update the navigation 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) to register the lesson.**

The AI Engineering From Scratch curriculum organizes hands-on tutorials into independent lesson folders within the `phases/` directory. Adding a new lesson to the rohitg00/ai-engineering-from-scratch repository requires scaffolding the correct folder structure, writing standardized documentation, and updating the navigation tables that the site generator parses. This guide covers the exact file paths and validation steps defined in the repository's contribution workflow.

## Create the Lesson Folder Structure

Every lesson must reside in a path following the convention `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `NN` is the phase number and `MM` is the lesson number. For example, a new lesson numbered 23 in Phase 3 would live at `phases/03-deep-learning-core/23-my-new-lesson/`.

Inside this folder, you must create three subdirectories:

- **`code/`** – Stores runnable implementations in Python, TypeScript, Rust, or Julia.
- **`docs/`** – Contains the narrative documentation, specifically the required [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) file.
- **`outputs/`** – Holds optional deliverables such as prompts, skills, agents, or MCP servers produced by the lesson.

The exact folder skeleton is documented in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7–21). You can copy this template to scaffold your new lesson quickly.

## Write the Lesson Documentation

The primary content file is [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md). This file must begin with a standardized front-matter block that the site generator and readers use to filter content:

```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 defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 35–80):

1. **Problem** – Define the challenge.
2. **Concept** – Explain the theory.
3. **Build It** – Implement the solution.
4. **Use It** – Demonstrate usage.
5. **Ship It** – Production considerations.
6. **Exercises** – Practice problems.

## Register the Lesson in Navigation

The curriculum UI is built from 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). The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses these files to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), which serves as the site's source of truth.

To make your lesson discoverable:

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

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

```

**Update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** by adding a matching entry under the correct phase section, using the status glyph `⬚` for work-in-progress:

```markdown
⬚ 23  My New Lesson

```

After editing these files, run the site generator locally to verify integration. According to [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) (line 22), only the timestamp in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) should change if the registration is correct.

## Submit Your Changes via Pull Request

The repository enforces a strict "one commit per lesson" rule and uses conventional commit prefixes. Follow this workflow:

1. **Fork** the repository and create a feature branch (e.g., `add-lesson-phase3-23-my-new-lesson`).
2. **Commit** all changes for the lesson folder, [`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) together.
3. **Test** your code by running `python -m unittest discover` inside the lesson's `code/` folder.
4. **Push** your branch and open a PR with a title like `feat(phase-03/23): add my-new-lesson`.

The CI pipeline automatically validates the README/ROADMAP integrity and regenerates the site data.

### Complete Workflow Example

Below is a minimal shell script demonstrating the full addition process:

```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. Edit documentation

$EDITOR phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

# 4. Add 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

# 5. Update README.md table (manual step)

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

# 6. Update ROADMAP.md (manual step)

# Add: ⬚ 23  My New Lesson

# 7. Test

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

# 8. Commit and push

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

```

## Summary

- **Structure**: Place lessons at `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with mandatory `code/`, `docs/`, and `outputs/` folders.
- **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 follow the six-beat narrative structure.
- **Registration**: Append rows to the phase 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) so [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) can discover the content.
- **Validation**: Run unit tests locally and verify only the timestamp changes in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) after running the site generator.
- **Submission**: Use conventional commit messages (`feat(phase-XX/YY): description`) and bundle all changes into a single commit per lesson.

## Frequently Asked Questions

### What is the exact 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, lesson 5 in phase 2 would be `phases/02-foundations/05-embedding-basics/`. This structure is required for [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to parse the curriculum correctly.

### Do I need to manually update the website HTML after adding a lesson?

No. The curriculum uses a static site generator driven by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js). This script automatically parses [`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), and lesson metadata to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). Simply updating the markdown tables and pushing your changes triggers the CI pipeline to rebuild the site.

### How do I mark a lesson as work-in-progress in the roadmap?

Use the glyph `⬚` (empty box) in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to indicate work-in-progress status. When the lesson is complete, update this to `✅`. The repository maintains a "readme-counts-sync" CI job that validates these glyphs match the actual folder structure.

### Can I include multiple programming languages in a single lesson?

Yes. The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front matter supports multiple languages in the **Languages** field (e.g., `Python, TypeScript`). Place language-specific code in the `code/` subdirectory, organizing by file extension or subfolders as needed. Ensure you list all supported languages in the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) table row when registering the lesson.