Essential Components and Expected Structure of AI Engineering Lesson Directories

Every AI Engineering lesson directory in the rohitg00/ai-engineering-from-scratch repository follows a strict, reproducible layout comprising docs/en.md, code/, outputs/, and quiz.json to support the "explain → manipulate → build → ship → verify" learning loop.

The rohitg00/ai-engineering-from-scratch curriculum organizes content into self-contained lesson directories that guarantee consistency, testability, and reusability. Understanding the essential components and expected structure within each AI Engineering lesson directory is critical for contributors and learners who need to navigate the codebase or scaffold new lessons according to the canonical LESSON_TEMPLATE.md specification.

The Pedagogical Loop Driving Structure

The repository enforces a specific cognitive loop across every lesson: explain → manipulate → build → ship → verify. This pattern ensures that theoretical concepts in the documentation lead directly to executable code, reusable artifacts, and validated assessments. Each directory component maps to a specific phase of this loop, creating a deterministic path from reading to implementation to validation.

Required Directory Components

Each lesson directory must contain six core components. Omitting any required component breaks the CI validation harness and prevents the site generator (site/build.js) from building navigation.

docs/en.md (The Narrative Layer)

The docs/en.md file provides the human-readable lesson description, learning objectives, and conceptual narrative. It must begin with a YAML front-matter block specifying Title, Type, Languages, Prerequisites, and Time.

Required sections include:

• Learning Objectives
• Problem
• Concept
• Build It
• Use It
• Ship It
• Exercises
• Key Terms
• Further Reading

Reference the canonical example at phases/14-agent-engineering/01-the-agent-loop/docs/en.md.

code/ (The Implementation Layer)

The code/ directory contains runnable implementations. At minimum, it must include a main.py file (or main.ts, main.rs, main.jl for additional languages declared in the front-matter).

Requirements include:

• A 4-6 line header comment at the top of main.* citing the lesson's docs/en.md path
• A tests/ subfolder containing ≥ 5 deterministic unit tests invocable via the language's standard test runner (e.g., python3 -m unittest discover)

For example, phases/14-agent-engineering/01-the-agent-loop/code/main.py demonstrates the required header format and imports.

outputs/ (The Artifact Layer)

The outputs/ directory stores reusable artifacts that downstream lessons can import, fostering a composable skill library. These artifacts follow strict front-matter schemas:

• prompt-*.md files following the markdown prompt schema
• skill-*.md files following the skill front-matter schema

See phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md for a valid skill artifact implementation.

quiz.json (The Assessment Layer)

Every lesson must include a quiz.json file adhering to a strict 6-question schema: 1 pre-assessment, 3 check-point questions, and 2 post-assessment questions. The JSON object must contain lesson, title, and a questions array with zero-based correct indices.

Example structure:

{
  "lesson": "01-the-agent-loop",
  "title": "The Agent Loop",
  "questions": [
    {"stage":"pre","question":"What is this lesson about?","options":["A","B","C","D"],"correct":0,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":1,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":2,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":1,"explanation":""},
    {"stage":"post","question":"Placeholder?","options":["A","B","C","D"],"correct":3,"explanation":""},
    {"stage":"post","question":"Placeholder?","options":["A","B","C","D"],"correct":0,"explanation":""}
  ]
}

Reference the live example at phases/14-agent-engineering/01-the-agent-loop/quiz.json.

notebook/ (Optional Interactive Layer)

An optional notebook/ directory may contain a single lesson.ipynb file for interactive experimentation and rapid prototyping. While not required for CI validation, this component supports the "manipulate" phase of the learning loop.

Root README Integration

The repository root README.md must list each lesson in a master table using the markdown link format [Title](phases/NN-phase-slug/MM-lesson-slug/). This entry drives the site generator for automatic navigation generation and ensures the lesson is discoverable.

The Template Specification

All structural requirements are codified in LESSON_TEMPLATE.md at the repository root. This document mandates the exact folder hierarchy:

NN-lesson-name/
├── code/
│   ├── main.py            (primary implementation)
│   ├── main.ts            (optional TypeScript)
│   ├── main.rs            (optional Rust)
│   └── main.jl            (optional Julia)
├── notebook/
│   └── lesson.ipynb
├── docs/
│   └── en.md
├── outputs/
│   ├── prompt-*.md
│   └── skill-*.md
└── quiz.json

Violating this hierarchy causes the CI pipeline to reject the lesson.

Scaffolding a New Lesson

To ensure compliance with the expected structure, run the following bash script from the repository root. It generates a fully-compliant lesson directory ready for content authoring and CI validation:

#!/usr/bin/env bash

# scaffold_new_lesson.sh – creates a lesson skeleton from the template.

set -euo pipefail

PHASE=$1          # e.g. 14-agent-engineering

SLUG=$2           # e.g. 99-demo-lesson

BASE_DIR="phases/$PHASE"

mkdir -p "$BASE_DIR/$SLUG"/{code,docs,outputs,notebook}
cp LESSON_TEMPLATE.md "$BASE_DIR/$SLUG/README.md"

# Minimal placeholder files

cat > "$BASE_DIR/$SLUG/docs/en.md" <<'EOF'

# Demo Lesson

> A short description.

**Type:** Build
**Languages:** Python
**Prerequisites:** None
**Time:** ~10 minutes

## Learning Objectives

- Understand the scaffolding process.
EOF

cat > "$BASE_DIR/$SLUG/code/main.py" <<'EOF'

# Minimal implementation – prints “Hello, world!”

print("Hello, world!")
EOF

cat > "$BASE_DIR/$SLUG/quiz.json" <<'EOF'
{
  "lesson": "99-demo-lesson",
  "title": "Demo Lesson",
  "questions": [
    {"stage":"pre","question":"What is this lesson about?","options":["A","B","C","D"],"correct":0,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":1,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":2,"explanation":""},
    {"stage":"check","question":"Placeholder?","options":["A","B","C","D"],"correct":1,"explanation":""},
    {"stage":"post","question":"Placeholder?","options":["A","B","C","D"],"correct":3,"explanation":""},
    {"stage":"post","question":"Placeholder?","options":["A","B","C","D"],"correct":0,"explanation":""}
  ]
}
EOF

Running bash scaffold_new_lesson.sh 14-agent-engineering 99-demo-lesson produces a directory structure that passes all validation checks.

Summary

• Every lesson follows the explain → manipulate → build → ship → verify pedagogical loop codified in the curriculum design
• Required components include: docs/en.md (narrative), code/ with tests/ (executable implementation), outputs/ (artifacts), and quiz.json (assessment)
• The optional notebook/lesson.ipynb supports interactive experimentation but is not required for CI validation
• LESSON_TEMPLATE.md at the repository root provides the canonical specification for folder hierarchy and file conventions
• Root README.md entries drive the site generator, making lessons discoverable and navigable

Frequently Asked Questions

What is the minimum required file structure for a valid lesson?

A valid lesson requires four mandatory components: docs/en.md with proper front-matter, code/main.py (or equivalent) with a tests/ subdirectory containing at least five unit tests, outputs/ for artifacts, and quiz.json following the 6-question schema. Additionally, the lesson must be linked in the root README.md to be discoverable by the site generator.

How does the quiz.json schema enforce assessment standards?

The quiz.json schema enforces a specific 6-question structure: 1 pre-assessment question to establish baseline knowledge, 3 check-point questions to verify comprehension during the lesson, and 2 post-assessment questions to measure learning gains. Each question must use zero-based indexing for the correct field, ensuring automated grading systems can parse answers deterministically.

Can I implement a lesson in languages other than Python?

Yes. While Python is the default language (requiring main.py), you may provide additional implementations in TypeScript (main.ts), Rust (main.rs), or Julia (main.jl). However, you must declare these languages in the docs/en.md front-matter, and every language implementation must include its own tests/ subdirectory with ≥ 5 deterministic unit tests.

How do outputs/ artifacts enable composable skill libraries?

The outputs/ directory stores skill-*.md and prompt-*.md files that follow standardized front-matter schemas. Downstream lessons can import these artifacts by path reference, allowing learners to build upon previous work without copy-pasting code. This creates a composable skill library where complex agent behaviors assemble from modular, tested components produced in earlier lessons.

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