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

To add a new lesson to the rohitg00/ai-engineering-from-scratch curriculum, scaffold the directory phases/NN-phase-slug/MM-new-lesson/ with the mandatory four-folder layout, populate docs/en.md with YAML-like front-matter, implement the source code with a path-citing header, provide at least five unit tests, define a quiz.json following the schema, and register the entry in README.md and ROADMAP.md before committing atomically.

The rohitg00/ai-engineering-from-scratch repository organizes its curriculum into self-contained lessons that follow a strict contract defined in AGENTS.md. Adding a new lesson requires adhering to a specific file structure and metadata format that enables automated catalog generation, site building, and CI validation. This guide provides the exact sequence of steps and file templates needed to integrate a new lesson seamlessly.

Step-by-Step Guide to Adding a New Lesson

1. Scaffold the Directory Structure

Create the lesson directory under the appropriate phase folder. The path must follow the pattern phases/NN-phase-slug/MM-new-lesson/ and contain four mandatory subdirectories.

mkdir -p phases/01-math-foundations/99-matrix-multiplication/{docs,code/tests,outputs}

This layout—docs/, code/, code/tests/, and outputs/—is enforced by the lesson contract in AGENTS.md (lines 63-79) and is required for the build pipeline to recognize the lesson.

2. Document the Lesson in docs/en.md

Every lesson requires a docs/en.md file with structured front-matter that drives the autogenerated README tables and roadmap. The front-matter must include the title, one-line hook, type, languages, prerequisites, time estimate, and learning objectives.

# Matrix Multiplication

> Multiply two matrices element-wise.

**Type:** Build
**Languages:** python
**Prerequisites:** Linear Algebra Intuition
**Time:** ~30min

## Learning Objectives

- Derive the matrix-product formula
- Implement a naïve O(n³) multiplication
- Validate with unit tests

According to the AGENTS.md specification (lines 65-79), this metadata is parsed by site/build.js to generate static site navigation and lesson cards.

3. Implement the Core Code

Create code/main.<lang> (e.g., code/main.py) and begin with a 4-6 line header comment that anchors the source file to its documentation. This satisfies the code/ contract defined in AGENTS.md (lines 102-107).

# File: code/main.py

# Lesson: phases/01-math-foundations/99-matrix-multiplication/docs/en.md

# Implements a naïve matrix multiplication from scratch.

import numpy as np

def matmul(A: np.ndarray, B: np.ndarray) -> np.ndarray:
    """Return A @ B using a triple-nested loop."""
    assert A.shape[1] == B.shape[0], "inner dimensions must match"
    C = np.zeros((A.shape[0], B.shape[1]), dtype=A.dtype)
    for i in range(A.shape[0]):
        for j in range(B.shape[1]):
            for k in range(A.shape[1]):
                C[i, j] += A[i, k] * B[k, j]
    return C

4. Write Comprehensive Unit Tests

Populate code/tests/test_main.py with at least five tests exercising the public API. The test suite ensures the lesson runs end-to-end and passes CI gates.

import unittest
import numpy as np
from ..main import matmul

class TestMatMul(unittest.TestCase):
    def test_identity(self):
        I = np.eye(3)
        A = np.random.randn(3, 3)
        self.assertTrue(np.allclose(matmul(A, I), A))

    def test_random(self):
        A = np.random.randn(2, 3)
        B = np.random.randn(3, 4)
        self.assertTrue(np.allclose(matmul(A, B), A @ B))

if __name__ == "__main__":
    unittest.main()

5. Configure the Assessment Quiz

Create quiz.json in the lesson root following the schema from AGENTS.md (lines 83-98). Include pre-check, check, and post-quiz questions.

{
  "lesson": "99-matrix-multiplication",
  "title": "Matrix Multiplication",
  "questions": [
    { "stage": "pre",   "question": "What does A @ B represent?", "options": ["Sum", "Product", "Difference", "None"], "correct": 1, "explanation": "" },
    { "stage": "check", "question": "What is the time complexity of the naïve algorithm?", "options": ["O(n)", "O(n²)", "O(n³)", "O(log n)"], "correct": 2, "explanation": "" },
    { "stage": "check", "question": "Which dimension must match for multiplication?", "options": ["Rows-Rows", "Cols-Cols", "Rows-Cols", "Cols-Rows"], "correct": 3, "explanation": "" },
    { "stage": "check", "question": "What is the result of multiplying a matrix by the identity matrix?", "options": ["Zero matrix", "The original matrix", "Transposed matrix", "None"], "correct": 1, "explanation": "" },
    { "stage": "post",  "question": "Can the algorithm be parallelised?", "options": ["Yes", "No", "Only on GPUs", "Only on CPUs"], "correct": 0, "explanation": "" },
    { "stage": "post",  "question": "Which library provides a faster implementation?", "options": ["NumPy", "SciPy", "Pandas", "Matplotlib"], "correct": 0, "explanation": "" }
  ]
}

6. Register in Public Indexes

Update the master README.md by inserting a row into the lessons table so the site builder can discover the lesson.

| # | Lesson | Type | Lang |

|:---:|--------|:----:|------|
| 99 | [Matrix Multiplication](phases/01-math-foundations/99-matrix-multiplication/) | Build | Python |

Simultaneously, update ROADMAP.md to reflect the lesson status (e.g., "WIP → Done").

7. Validate Locally and Commit

Run the per-lesson sanity checks before committing. Navigate to the code directory and execute the implementation and tests.

cd phases/01-math-foundations/99-matrix-multiplication/code
python3 main.py && python3 -m unittest discover tests -v

Once validation passes, commit atomically following the hard rules in AGENTS.md (lines 38-47). The commit must be single-purpose and use conventional commit format.

git add phases/01-math-foundations/99-matrix-multiplication README.md ROADMAP.md
git commit -m "feat(phase-01/99): add matrix-multiplication"
git push -u origin <your-branch>
gh pr create --title "feat(phase-01/99): add matrix-multiplication" --body "<5-line summary>"

Summary

• Directory Layout: Create phases/NN-phase-slug/MM-lesson/ with docs/, code/tests/, and outputs/ subdirectories.
• Documentation: Write docs/en.md with mandatory front-matter (Type, Languages, Prerequisites, Time, Learning Objectives).
• Code Standards: Implement code/main.<lang> with a header comment citing the lesson path, and provide at least five unit tests in code/tests/.
• Assessment: Define quiz.json with pre-check, check, and post-quiz questions per the schema.
• Registration: Add entries to README.md (lessons table) and ROADMAP.md (status tracking).
• Validation: Run local tests (python3 main.py && python3 -m unittest discover tests -v) before committing.
• Git Workflow: Commit atomically with conventional commit messages (feat(phase-NN/MM): add <slug>) and open a pull request.

Frequently Asked Questions

What happens if I don't include the front-matter in docs/en.md?

The curriculum automation relies on the front-matter to populate the README tables and generate the static site navigation. Without it, site/build.js will fail to index your lesson, and it will not appear in the public catalog.

Can I use a language other than Python for the implementation?

Yes. The Languages field in docs/en.md accepts any value, and code/main.<lang> can use any extension. However, you must still provide a test suite in code/tests/ and ensure the header comment in main.<lang> cites the correct path to docs/en.md.

Is the outputs/ directory mandatory?

No. The outputs/ folder is optional and only required if your lesson generates a reusable artifact such as a skill, prompt, or MCP server. If present, place a Markdown file describing the artifact (e.g., outputs/skill-matrix-multiplication.md) so it can be discovered by scripts/install_skills.py.

How many questions must quiz.json contain?

The schema requires a minimum structure covering pre-check, check, and post stages. While the exact number is not strictly enforced, the standard template includes six questions to adequately assess comprehension before, during, and after the lesson.

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