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

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:

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:

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:

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

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 that serves as a lesson index. Add your new lesson to maintain discoverability:

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

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

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	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 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, 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.

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