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

> Contribute a new lesson to the AI Engineering from Scratch curriculum. Learn how to structure your lesson, write compelling documentation, and register it within the repository.

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

---

**To contribute a new lesson to the AI Engineering from Scratch curriculum, scaffold a numbered folder under the appropriate phase in `phases/`, populate it with `code/`, `docs/`, and `outputs/` subdirectories, write the narrative in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) following the standard six-beat structure, and register 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 rohitg00/ai-engineering-from-scratch repository organizes its curriculum into independent lesson folders that feed a static site generator. When you contribute a new lesson to the AI Engineering curriculum, you must adhere to a strict folder hierarchy and documentation protocol that allows [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to discover and render your content correctly.

## Lesson Folder Structure and Requirements

Every lesson lives in a path following the pattern `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `<NN>` is the phase number and `<MM>` is the lesson number. According to the [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) scaffold (lines 7-21), each lesson folder must contain three subdirectories:

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

The repository enforces a "one commit per lesson" rule, so all changes for a single lesson must be contained within one commit.

## Writing the Lesson Documentation

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 shown in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25-34). The header follows this format:

```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

```

After the front matter, the narrative must follow the six-beat structure documented in the template (lines 35-80):

1. **Problem** – Define the challenge being solved.
2. **Concept** – Explain the theoretical foundation.
3. **Build It** – Step-by-step implementation guide.
4. **Use It** – Demonstration of the working code.
5. **Ship It** – Deployment or production considerations.
6. **Exercises** – Hands-on tasks for the reader.

## Registering the Lesson in Navigation Tables

The curriculum website 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), which are parsed by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) (as described in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md), lines 8-11).

To make the lesson discoverable:

- **In [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md):** Append a row to the appropriate phase table using the format:
  ```markdown
  | 23 | [My New Lesson](phases/03-deep-learning-core/23-my-new-lesson/) | Build | Python |
  ```

- **In [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md):** Add 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 that only a timestamp change appears in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) (see [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) line 22).

## Submitting Your Contribution

The pull request workflow follows strict conventions to maintain CI integrity:

1. Fork the repository and create a branch named `add-lesson-phase<NN>-<MM>-<lesson-slug>`.
2. Ensure your implementation includes unit tests in the `code/` folder and run them with `python -m unittest discover`.
3. Commit using a conventional title format: `feat(phase-03/23): add my-new-lesson`.
4. Push the branch and open a PR; the CI pipeline will automatically regenerate site data and enforce README/ROADMAP integrity.

## Complete Workflow Example

The following shell commands demonstrate the full process, replacing placeholders with your actual phase and lesson identifiers:

```bash

# 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

# 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

# Edit documentation

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

# 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

# Update navigation tables in README.md and ROADMAP.md

# (Add row to phase table and roadmap entry)

# Run tests

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

# 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

- **Create the folder structure** under `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with `code/`, `docs/`, and `outputs/` subdirectories.
- **Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** using the front-matter template and six-beat narrative structure defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).
- **Update 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 with [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js).
- **Submit a single-commit PR** with a conventional title like `feat(phase-03/23): add my-new-lesson` after verifying local tests pass.

## Frequently Asked Questions

### What is the required folder structure for a new lesson?

You must create a folder under `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` containing three subdirectories: `code/` for implementations, `docs/` for the [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) narrative file, and `outputs/` for optional artifacts. This structure is enforced by the [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator and documented in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7-21).

### How do I format the lesson documentation file?

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must start with a front-matter block specifying Type, Languages, Prerequisites, and Time, followed by a six-beat narrative structure: Problem, Concept, Build It, Use It, Ship It, and Exercises. Refer to [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25-80) for the exact scaffold.

### Where do I register the lesson so it appears on the website?

Add a row to the appropriate phase table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and a corresponding entry in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) using the `⬚` status glyph. These tables are parsed by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to generate the site navigation and data files.

### What commit message format should I use for my contribution?

Use conventional commit format: `feat(phase-<NN>/<MM>): add <lesson-slug>`. The repository requires exactly one commit per lesson, so stage all changes—including the new lesson folder and updates to [`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)—in a single commit before opening your pull request.