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

> Learn to add a new lesson to the AI Engineering from Scratch curriculum. Follow steps for scaffolding, frontmatter, code, and quizzes, then integrate your content easily.

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

---

**Adding a new lesson to the curriculum requires scaffolding a numbered directory with [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh), filling in the required [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) frontmatter block, implementing self-contained code and a six-question [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), then registering the lesson 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) before running [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and committing atomically.**

The `rohitg00/ai-engineering-from-scratch` repository is organized into numbered phases where every lesson follows a strict contract enforced by automated tooling. If you want to add a new lesson to the curriculum, you must adhere to the frontmatter schema, directory layout, and validation rules defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).

## Choose a Phase and Scaffold the Lesson Skeleton

### Follow the Numbering Convention

Lessons live inside phase folders such as `phases/03-deep-learning-core`. Both phase and lesson numbers use a two-digit prefix and follow the `NN-kebab-case` naming pattern. The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) helper validates this format at lines 42–45 before creating any files.

### Run the Scaffold Script

Execute the script with the phase folder, lesson slug, and human-readable title:

```bash
scripts/scaffold-lesson.sh 03-deep-learning-core 05-backpropagation "Backpropagation from Scratch"

```

This generates the standard layout—`code/`, `docs/`, `outputs/`, and `notebook/`—and writes a starter [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) containing a minimal frontmatter skeleton (lines 57–66 in the script).

## Meet the Frontmatter Requirements in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must begin with a strict frontmatter block that feeds the site's build pipeline and automated validators. The **Lesson contract** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (section *Lesson contract* → *docs/en.md frontmatter*, lines 22–31) mandates the following fields:

```markdown

# Backpropagation from Scratch

> One‑line motto that captures the core idea.

**Type:** Build
**Languages:** Python, TypeScript, Rust, Julia
**Prerequisites:** <comma‑list of prior lessons>
**Time:** ~75 minutes

```

These fields power the README table, the site index generated by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), and the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validation step.

## Implement Code, Quizzes, and Output Artifacts

### Write Self-Contained Code

Place implementation files under the lesson's `code/` directory (for example, [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) or [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts)). Every file must run without errors using a direct command such as `python code/main.py`, and the code must remain self-contained with no external API keys or hidden state.

### Add a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)

Each lesson ships a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) that conforms to the schema documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (section *quiz.json schema*). The file must contain exactly six questions: one pre-assessment, three check-ins, and two post-assessment questions. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validator enforces this shape automatically.

### Populate the `outputs/` Directory

If your lesson produces prompts, skills, agents, or MCP servers, store them as Markdown files inside `outputs/` using the proper headers shown in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 107–133).

## Register the Lesson in the Curriculum Index

### Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)

Add a table row to the appropriate phase section so readers can discover the lesson. Based on existing entries around line 45, the row follows this pattern:

```markdown
| 05 | [Backpropagation from Scratch](phases/03-deep-learning-core/05-backpropagation/) | Build | Python |

```

### Update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)

Insert a matching entry under the correct phase header. [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) directly drives the autogenerated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) consumed by the website.

## Validate Locally and Commit Atomically

### Run the Audit Scripts

Before committing, verify your lesson passes the automated checks:

```bash
python3 scripts/audit_lessons.py
python3 scripts/check_readme_counts.py
cd phases/03-deep-learning-core/05-backpropagation/code
python3 -m unittest discover tests -v

```

All checks must pass; [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) is blocking in CI as well.

### Commit with Conventional Style

The repository requires exactly one commit per lesson, as noted in the **Hard rules** section of [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 13–15). Use conventional-commit formatting:

```bash
git add phases/03-deep-learning-core/05-backpropagation README.md ROADMAP.md
git commit -m "feat(phase-03/05): Backpropagation from Scratch"
git push origin my-new-lesson-branch

```

After pushing, open a pull request. CI will re-run [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py), regenerate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) via [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) on merge, and sync README counts via [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py).

## Summary

- Use [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) to create a correctly numbered `NN-kebab-case` lesson directory with `code/`, `docs/`, `outputs/`, and `notebook/` subfolders.
- The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) frontmatter block must include **Type**, **Languages**, **Prerequisites**, and **Time** according to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract.
- Every lesson needs a six-question [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) and self-contained code with no external secrets.
- Register the lesson in 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) so the site index and human navigation stay in sync.
- Run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) locally and commit atomically with a conventional-commit message; CI enforces the same rules before merge.

## Frequently Asked Questions

### What happens if the frontmatter fields are missing or malformed?

[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) will fail with a validation error because the frontmatter block drives [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), the README table, and the curriculum index. Every field listed in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lesson contract is mandatory.

### Can I split a lesson across multiple commits?

No. The **Hard rules** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 13–15) require exactly one atomic commit per lesson. The scaffold script even prints the suggested conventional-commit message to make this easy.

### Where is the quiz schema defined?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) schema is defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the section *quiz.json schema*. It requires precisely six questions in the order 1 pre, 3 check, and 2 post, and [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) enforces this structure during local and CI validation.

### How does the website discover a new lesson?

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator reads [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), while [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) supplies the human-readable navigation links. You must update both files after scaffolding so the lesson appears in the site index and the curriculum table.