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

Adding a new lesson to the curriculum requires scaffolding a numbered directory with scripts/scaffold-lesson.sh, filling in the required docs/en.md frontmatter block, implementing self-contained code and a six-question quiz.json, then registering the lesson in README.md and ROADMAP.md before running 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 and 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 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:

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 containing a minimal frontmatter skeleton (lines 57–66 in the script).

Meet the Frontmatter Requirements in docs/en.md

The 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 (section Lesson contract → docs/en.md frontmatter, lines 22–31) mandates the following fields:

# 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, and the 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 or 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

Each lesson ships a quiz.json that conforms to the schema documented in 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 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 (lines 107–133).

Register the Lesson in the Curriculum Index

Update 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:

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

Update ROADMAP.md

Insert a matching entry under the correct phase header. ROADMAP.md directly drives the autogenerated 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:

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 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 (lines 13–15). Use conventional-commit formatting:

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, regenerate site/data.js via site/build.js on merge, and sync README counts via scripts/check_readme_counts.py.

Summary

• Use 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 frontmatter block must include Type, Languages, Prerequisites, and Time according to the AGENTS.md contract.
• Every lesson needs a six-question quiz.json and self-contained code with no external secrets.
• Register the lesson in both README.md and ROADMAP.md so the site index and human navigation stay in sync.
• Run 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 will fail with a validation error because the frontmatter block drives site/build.js, the README table, and the curriculum index. Every field listed in the AGENTS.md lesson contract is mandatory.

Can I split a lesson across multiple commits?

No. The Hard rules in 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 schema is defined in 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 enforces this structure during local and CI validation.

How does the website discover a new lesson?

The site/build.js generator reads ROADMAP.md to produce site/data.js, while 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.

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