Folder Structure for Adding a New Lesson to AI Engineering From Scratch

To add a new lesson to ai-engineering-from-scratch, you must create a directory under phases/<NN>-<phase-name>/<NN>-<lesson-slug>/ containing code/, docs/, and outputs/ subdirectories, with at least one implementation file in code/ and a front-matter-backed Markdown file in docs/en.md.

The rohitg00/ai-engineering-from-scratch repository enforces a rigid curriculum architecture to ensure every lesson integrates seamlessly with the automated tooling and documentation pipeline. This standardized folder structure for adding a new lesson is documented in LESSON_TEMPLATE.md and validated through the repository's CI checks.

Top-Level Phase Organization

All lessons reside within the phases/ directory at the repository root. This folder groups content by curriculum phase using a strict naming convention: <NN>-<phase-name>, where NN represents a two-digit sequential prefix (e.g., 04-computer-vision). The hyphenated name describes the phase domain and must remain consistent across all lessons within that phase.

Lesson Directory Naming Convention

Inside a phase folder, each lesson lives in its own directory named <NN>-<lesson-slug>. The two-digit prefix must represent the next sequential number within that specific phase, while the slug briefly describes the lesson topic (e.g., 04-image-fundamentals). This numbering ensures the curriculum maintains logical progression and allows build scripts to order content correctly.

Required Subdirectories

Every lesson directory must contain three mandatory subdirectories and one optional folder. The structure is enforced by the template defined in LESSON_TEMPLATE.md and referenced in the README's "The shape of a lesson" section.

The code/ Directory

The code/ folder houses all runnable implementations. You must provide at least one primary implementation file named main.<ext>. The repository supports multilingual implementations:

• main.py for Python
• main.ts for TypeScript (optional)
• main.rs for Rust (optional)
• main.jl for Julia (optional)

Any additional language files must match the languages declared in the lesson's front-matter metadata.

The docs/ Directory

The docs/ folder must contain en.md, the canonical lesson document. This file requires strict front-matter schema compliance including fields for title, type (e.g., Learn or Build), languages, prerequisites, and time. The narrative content follows this front-matter block.

The outputs/ Directory

The outputs/ folder stores reusable artifacts that the lesson produces. This includes prompt-*.md files containing LLM prompts and skill-*.md files documenting acquired skills. These artifacts ship with the lesson for learner reference.

The notebook/ Directory (Optional)

An optional notebook/ subdirectory may contain lesson.ipynb for interactive Jupyter-based experimentation. While not required, this directory supports hands-on exploration when complex visualization or iterative development is beneficial.

Automated Folder Creation

The AGENTS.md file's "New-lesson onboarding" section recommends automating scaffold creation to prevent structural errors. Use this Bash snippet to generate a compliant lesson skeleton:

# Configure these variables for your specific lesson

phase="04-computer-vision"
lesson_num="04"               # Next sequential number in the phase

lesson_slug="image-fundamentals"

lesson_dir="phases/${phase}/${lesson_num}-${lesson_slug}"
mkdir -p "${lesson_dir}/code" "${lesson_dir}/docs" "${lesson_dir}/outputs"

# Create a placeholder Python implementation

cat > "${lesson_dir}/code/main.py" <<'PY'
def run():
    print("Hello, AI Engineering!")
PY

# Create documentation with required front-matter

cat > "${lesson_dir}/docs/en.md" <<'MD'
---
title: "Image Fundamentals: Pixels, Channels, Color Spaces"
type: Learn
languages: [Python]
prerequisites: []
time: "~30 minutes"
---

Understanding the raw visual data that feeds all vision models.
MD

This script produces a directory structure that passes the repository's structural validation checks.

Authoritative Source Files

Three files define and enforce the required scaffolding:

• LESSON_TEMPLATE.md: Provides the definitive folder-structure diagram and the exact Markdown template for docs/en.md front-matter.
• README.md (section The shape of a lesson): Visualizes the hierarchy within the full curriculum context and links each lesson from the main index.
• AGENTS.md (section New-lesson onboarding): Lists the exact post-creation steps, including updating the main README and ROADMAP files and running CI checks.

Summary

• Lessons must reside under phases/<NN>-<phase-name>/<NN>-<lesson-slug>/ using sequential two-digit numbering.
• The code/ directory requires at least one main.<ext> implementation file, with Python being the primary supported language.
• Documentation must live in docs/en.md and follow the strict front-matter schema defined in LESSON_TEMPLATE.md.
• Generated artifacts ship in outputs/ as prompt-*.md or skill-*.md files.
• The structure is mandatory and validated against the templates in LESSON_TEMPLATE.md and README.md.

Frequently Asked Questions

What happens if I don't include the two-digit numeric prefix in the lesson folder name?

The curriculum build system and linking logic in README.md depend on lexicographical ordering of these prefixes to sequence lessons correctly. Omitting the prefix or using non-sequential numbers will break the automated table of contents generation and cause CI validation failures.

Can I create a lesson with only a TypeScript implementation and no Python code?

While the code/ directory supports multiple languages, the curriculum requires at least one implementation file. However, the front-matter in docs/en.md must accurately reflect which languages are provided. If you list TypeScript in the front-matter but only provide main.ts, ensure the build agents in AGENTS.md are configured to handle language-specific validation for that lesson.

Where does the lesson metadata come from if not from the folder name?

The canonical metadata (title, type, prerequisites, estimated time) is parsed from the YAML front-matter in docs/en.md, not the directory name. The folder name provides only the URL slug and ordering information. The LESSON_TEMPLATE.md specifies the exact front-matter keys required for curriculum ingestion.

Is there a specific naming convention for files inside the outputs/ directory?

Yes. Prompt artifacts must follow the pattern prompt-*.md and skill documentation must follow skill-*.md. These naming conventions allow the repository's indexing scripts to automatically catalog reusable prompts and skills generated by each lesson, as described in the AGENTS.md onboarding guide.

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