# How to Add a New Lesson to the AI-For-Beginners Curriculum: A Step-by-Step Guide

> Learn how to add a new lesson to the AI-For-Beginners curriculum. Follow our step-by-step guide to structure your contribution and submit a pull request to the Microsoft repository.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Bold TLDR:** The correct way to add a new lesson to the AI-For-Beginners curriculum involves creating a numbered sub-directory under the appropriate topic folder in `lessons/`, adding a self-contained Jupyter notebook, and optionally updating the topic's README index before submitting a pull request.

The Microsoft AI-For-Beginners repository provides a structured 12-week curriculum for learning artificial intelligence fundamentals. Whether you're contributing a lesson on advanced neural architectures or a practical computer vision exercise, following the established directory conventions ensures your content integrates seamlessly with the existing course structure.

## Locating the Correct Topic Directory

All lessons reside in the top-level `lessons/` folder, organized by subject area and prefixed with numbers indicating their position in the overall curriculum sequence.

The repository uses this hierarchical structure:

```

lessons/
├── 1-IntroToAI/
├── 2-Symbolic/
├── 3-NeuralNetworks/
├── 4-ComputerVision/
├── 5-NLP/
├── 6-Other/
├── 7-GenAI/
        ...

```

Select the topic folder that best matches your lesson's subject matter. The numeric prefix (e.g., `3-NeuralNetworks`) corresponds to the week and topic ordering used throughout the course【https://github.com/microsoft/AI-For-Beginners/tree/main/lessons】.

## Creating the Lesson Structure

### Step 1: Name Your Lesson Directory

Inside the chosen topic folder, create a new sub-directory using the two-digit lesson number followed by a hyphenated descriptive title:

```bash
cd lessons/3-NeuralNetworks
mkdir 04-DeepLearning

```

This naming convention maintains consistent lesson ordering and produces clean URLs when the repository is browsed on GitHub.

### Step 2: Add the Core Notebook File

Create a Jupyter notebook with a filename matching your directory name:

```bash
cd 04-DeepLearning
touch DeepLearning.ipynb

```

Your notebook should follow the established pedagogical pattern found in existing lessons like the Perceptron lesson【https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb】:

- **Conceptual explanations** in markdown cells
- **Runnable code cells** demonstrating the technique
- **Self-contained imports** of all required libraries
- **Clear output** showing expected results

### Step 3: Include Supporting Assets

If your lesson requires images, datasets, or supplementary scripts, add them to the same lesson directory:

```bash

# Example asset structure

04-DeepLearning/
├── DeepLearning.ipynb      # Main lesson notebook

├── data/                   # Sample datasets

│   └── training_data.csv
└── images/                 # Diagrams and figures

    └── neural_arch.png

```

Reference assets using relative paths from the notebook location:

```python
import pandas as pd

# Load data from the local data folder

df = pd.read_csv('data/training_data.csv')

```

## Updating Curriculum Indexes

Each topic folder contains a [`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) that serves as a lesson index. Add your new lesson to maintain discoverability:

```markdown

## Neural Networks

| #  | Lesson | Notebook |

|---|--------|----------|
| 01 | Introduction to Neural Networks | [Notebook](01-Intro/README.ipynb) |
| 02 | Intro to Keras | [Notebook](02-Keras/Keras.ipynb) |
| 03 | Perceptron | [Notebook](03-Perceptron/Perceptron.ipynb) |
| 04 | Deep Learning | [Notebook](04-DeepLearning/DeepLearning.ipynb) |

```

This step is optional but strongly recommended for consistency with the repository's navigation patterns.

## Validating Your Lesson

Before committing, verify your notebook executes correctly in a clean environment using the project's conda specification:

```bash

# Create environment from project specification

conda env create -f ../../environment.yml -n ai-beginners
conda activate ai-beginners

# Execute notebook and check for errors

jupyter nbconvert --to notebook --execute DeepLearning.ipynb --output DeepLearning_test.ipynb

# Clean up test output

rm DeepLearning_test.ipynb

```

The [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file【https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml】 defines all dependencies required across the curriculum, ensuring reproducible execution.

## Submitting Your Contribution

### Commit Your Changes

Stage the complete lesson directory with descriptive commit messages:

```bash
git add .
git commit -m "Add 04-DeepLearning lesson to 3-NeuralNetworks

- Covers multi-layer perceptrons and activation functions
- Includes interactive visualization of forward propagation
- Self-contained with synthetic dataset generation"

```

### Open a Pull Request

Submit your PR against the `main` branch. The repository's continuous integration workflow will automatically validate your notebook execution. Address any CI failures before requesting review.

## Key File References

| File Path | Purpose |
|-----------|---------|
| `lessons/` | Root directory for all curriculum content【https://github.com/microsoft/AI-For-Beginners/tree/main/lessons】 |
| `lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb` | Reference implementation showing lesson structure and style【https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb】 |
| [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) | Conda environment ensuring dependency consistency【https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml】 |
| `lessons/{topic}/README.md` | Topic index to update with new lesson links |
| `.github/workflows/` | CI validation that executes contributed notebooks |

## Summary

- **Choose the correct topic directory** under `lessons/` based on your lesson subject and curriculum week
- **Create a numbered sub-directory** with format `NN-Lesson-Title` to maintain ordering
- **Author a self-contained Jupyter notebook** following the pedagogical style of existing lessons like `03-Perceptron`
- **Add supporting assets** in the same directory with relative path references
- **Update the topic README.md** to include your lesson in the navigation index
- **Validate execution** using the project's [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) before submission
- **Submit via pull request** for automated CI validation and maintainer review

## Frequently Asked Questions

### What notebook format should I use for a new lesson?

Use the standard Jupyter Notebook format (`.ipynb`) with clear markdown explanation cells alternating with executable code cells. The notebook must be self-contained—readers should execute cells sequentially without encountering import errors or missing data files. Refer to `03-Perceptron/Perceptron.ipynb` as the canonical example【https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb】.

### Can I contribute a lesson that uses external datasets?

Yes, though preference is given to lessons using synthetic data or small downloadable datasets. If external data is necessary, include a code cell that downloads or generates the data automatically, or place a small dataset (<10MB) directly in your lesson's `data/` sub-directory. Never require manual file placement by users.

### How are lesson numbers assigned when inserting between existing lessons?

The numbering scheme reflects curriculum sequence, not strict consecutive ordering. When inserting a lesson between existing entries, use a decimal-style intermediate number (e.g., `03-Perceptron` and `04-DeepLearning` could accommodate `03-5-ActivationFunctions`). Alternatively, coordinate with maintainers in your pull request to renumber affected lessons if a complete reordering is preferred.

### What triggers CI failure for a new lesson contribution?

The continuous integration workflow fails when notebooks contain execution errors, missing dependencies not declared in [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml), or outputs that create excessively large diffs. Run `jupyter nbconvert --execute` locally with a fresh kernel before submitting, and clear all cell outputs (`Kernel → Restart & Clear Output`) to minimize repository bloat.