Complete Frontmatter Schema Required for Lessons in docs/en.md

Every lesson in the rohitg00/ai-engineering-from-scratch repository must include a structured frontmatter block at the top of its docs/en.md file with seven specific metadata fields—Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives—to comply with the Lesson contract and pass automated validation.

The rohitg00/ai-engineering-from-scratch curriculum maintains consistency across 435 lessons through a strict frontmatter schema defined in the project's Lesson contract. This standardized metadata block enables automated tooling to validate lesson structure, generate the website, and synchronize the README table of contents. Understanding the required frontmatter schema is essential for contributors adding new lessons or modifying existing documentation.

The Seven Required Frontmatter Fields

According to the Lesson contract defined in AGENTS.md, every docs/en.md file must begin with a fenced markdown code block containing exactly seven metadata components. The block uses the markdown language tag and follows a precise hierarchical structure.

Title and Hook

The frontmatter opens with a level-one heading and a blockquote teaser:

• Title: # <Title> — A human-readable lesson title using standard Markdown heading syntax.

• Hook: > <One-line hook> — A concise teaser appearing directly under the title that describes the lesson's value proposition.

Classification and Technical Metadata

Three fields define the lesson's categorization and technical requirements:

• Type: **Type:** <Learn | Build | Reference> — Indicates the lesson's pedagogical purpose. Must be exactly one of these three values.
• Languages: **Languages:** <comma-list> — A comma-separated list of programming languages used in the lesson's code/main.* files. This must match the actual main.* files present in the lesson directory.
• Prerequisites: **Prerequisites:** <comma-list or None> — Other lesson slugs that must be completed first, or the literal string None if there are no dependencies.

Duration and Learning Outcomes

The final two fields establish time expectations and educational goals:

• Time: **Time:** ~<estimate> — Approximate duration in minutes, prefixed with a tilde (e.g., ~30).
• Learning Objectives: A level-two heading ## Learning Objectives followed by 4-6 bullet points (using - syntax), each starting with a verb describing what the learner will achieve.

Automated Validation of the Frontmatter Schema

The repository enforces this schema through automated tooling that parses docs/en.md files during CI/CD and local development workflows.

Validation via audit_lessons.py

The scripts/audit_lessons.py script parses the frontmatter block to verify compliance with the Lesson contract. It checks that Languages entries match actual main.* files in the code directory, validates that Learning Objectives contain the correct number of bullet points (4-6), and ensures all required fields are present and formatted correctly.

Site Generation and README Synchronization

The site/build.js script extracts the Title and file paths from the frontmatter to construct site/data.js, which drives the lesson website navigation. Missing or malformed frontmatter prevents the lesson from appearing in the generated website. Additionally, the README's automated table of contents pulls the Title directly from each lesson's frontmatter; inconsistencies break the auto-count logic that tracks the 435-lesson curriculum.

Compliant Frontmatter Examples for docs/en.md

The following examples demonstrate valid frontmatter structures for single-language and multi-language lessons.

Single-Language Python Lesson

# Gradient Clipping and AMP

> Master gradient clipping and automatic mixed precision in PyTorch.

**Type:** Build
**Languages:** Python
**Prerequisites:** 45-gradient-checkpointing
**Time:** ~30

## Learning Objectives

- Explain why gradient clipping stabilizes training.
- Implement torch.nn.utils.clip_grad_norm_.
- Configure AMP with torch.cuda.amp.
- Compare training speed with and without AMP.
- Evaluate model quality after clipping.

Multi-Language Lesson (Python and TypeScript)

# Multi‑Agent Coordination Protocol

> Design a communication protocol for distributed agents.

**Type:** Learn
**Languages:** Python, TypeScript
**Prerequisites:** 21-agent-economies, 03-communication-protocols
**Time:** ~45

## Learning Objectives

- Describe the role of a coordination protocol.
- Define a JSON schema for agent messages.
- Implement a broadcaster in Python.
- Implement a subscriber in TypeScript.
- Simulate a simple multi‑agent scenario.

Summary

• Seven mandatory fields: Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives must appear in every docs/en.md frontmatter block.
• Strict formatting: The block must be wrapped in a fenced markdown code block with the markdown specifier, following the exact hierarchical structure defined in AGENTS.md.
• Automation dependency: scripts/audit_lessons.py validates compliance, while site/build.js and README generators rely on this schema for site rendering and table-of-contents generation.
• Language matching: The Languages field must correspond exactly to the main.* files present in the lesson's code directory.

Frequently Asked Questions

What happens if my docs/en.md file is missing required frontmatter fields?

The scripts/audit_lessons.py validation script will flag the lesson as non-compliant during automated checks. Missing frontmatter also prevents the lesson from appearing in the website generated by site/build.js and breaks the README's automated lesson counter, effectively excluding the content from the curriculum index.

Can a single lesson specify multiple programming languages in the frontmatter?

Yes. The Languages field accepts a comma-separated list (e.g., Python, TypeScript) when the lesson contains multiple main.* files. However, every language listed must have a corresponding main.{ext} file in the lesson's code directory, or audit_lessons.py will report a validation error.

Where is the frontmatter schema contract formally defined?

The Lesson contract is formally specified in the AGENTS.md file at the repository root. This document defines the exact syntax, field order, and validation rules for the frontmatter block in docs/en.md files, serving as the authoritative reference for the 435-lesson curriculum standard.

How many learning objectives must a lesson include?

The schema requires exactly 4 to 6 bullet points under the ## Learning Objectives heading. Each bullet must start with a verb describing a measurable skill or knowledge outcome. The audit_lessons.py script explicitly counts these bullets and fails validation if the count falls outside this range.

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