How Lesson Outputs Are Organized in the Phases Directory: Structure and Naming Conventions

Lesson outputs in the ai-engineering-from-scratch repository are stored in an outputs/ subfolder within each lesson directory, following strict naming conventions where skills use the skill-<slug>.md pattern, prompts use prompt-<slug>.md, and JSON reports use <slug>_report.json or <slug>.json formats.

The phases directory in the rohitg00/ai-engineering-from-scratch curriculum uses a predictable hierarchy to store generated artifacts. This structure allows automation scripts like scripts/audit_lessons.py and the site generator site/build.js to discover, validate, and publish lesson content without manual configuration.

Directory Structure in the Phases Folder

Every lesson occupies a leaf folder under phases/<phase-number>-<phase-slug>/<lesson-number>-<lesson-slug>/. Inside this lesson folder, the outputs/ directory contains all generated artifacts.

The hierarchy follows this pattern:

phases/
└─ <phase-id>-<phase-slug>/
   └─ <lesson-id>-<lesson-slug>/
      ├─ docs/
      ├─ code/
      ├─ quiz.json
      └─ outputs/          ← generated artifacts

For example, the "End-to-End Safety Gate" lesson (phase 19, lesson 87) stores its artifacts in phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/. Specific files include skill-end-to-end-safety-gate.md and gate_trace.json, demonstrating how the outputs/ folder sits alongside docs/ and code/ folders at the lesson level.

Naming Conventions for Output Files

The repository enforces specific prefixes and extensions based on artifact type. All slugs use kebab-case to reflect the lesson's focus.

• Skill files: Named skill-<slug>.md (Markdown). These contain reusable skills that downstream lessons or agents can import.
• Prompt templates: Named prompt-<slug>.md (Markdown). These store ready-to-use prompts, often for debug assistants or environment checks.
• JSON reports: Named <slug>_report.json or <slug>.json. These contain structured data such as evaluation results, trace logs, or gate outputs.
• Miscellaneous artifacts: Named <slug>.md or <slug>.txt depending on content type, used for diagrams or helper documentation.

According to the repository source code, these patterns enable the site builder to scan and catalog outputs automatically without requiring a registry file.

How the Repository Enforces These Conventions

Two key scripts maintain the integrity of the lesson outputs organization:

• scripts/audit_lessons.py: Validates that each lesson contains an outputs/ folder and verifies that file naming conventions are respected across the curriculum.
• site/build.js: Generates the site's data.js by scanning outputs/ directories throughout the phases folder, relying on the consistent skill- and prompt- prefixes to categorize artifacts.

The AGENTS.md file documents the "one-commit-per-lesson" rule that governs this output placement, ensuring that generated artifacts are committed atomically with their respective lesson content.

Working with Lesson Outputs Programmatically

Because the outputs/ location is fixed and naming patterns are consistent, downstream lessons can import resources using relative paths.

Importing a Skill in Python

from pathlib import Path

# Navigate from current lesson to target lesson's outputs

skill_path = Path(__file__).parents[2] / "outputs" / "skill-end-to-end-safety-gate.md"

with open(skill_path, "r", encoding="utf-8") as f:
    safety_gate_markdown = f.read()

print("Loaded skill description:")
print(safety_gate_markdown[:200])

This pattern works for any lesson because the folder name is always outputs and skill files always start with skill-.

Reading a JSON Report in Node.js

const fs = require('fs');
const path = require('path');

const reportPath = path.join(
  __dirname, '..', '..', 'outputs', 'gate_trace.json'
);

const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
console.log('Gate trace entries:', report.length);

Both examples rely only on the fixed directory structure and naming conventions, remaining stable as new lessons are added to the phases directory.

Summary

• Lesson outputs are stored in an outputs/ subfolder inside each lesson directory at phases/<phase-id>-<slug>/<lesson-id>-<slug>/outputs/.
• Skill files use the pattern skill-<slug>.md, prompt files use prompt-<slug>.md, and JSON reports use <slug>_report.json or <slug>.json.
• The scripts/audit_lessons.py script validates compliance with these conventions.
• The site/build.js generator depends on this structure to build the curriculum site automatically.
• Consistent naming allows lessons to import artifacts from previous lessons using predictable relative paths.

Frequently Asked Questions

What is the exact path pattern for lesson outputs in the phases directory?

Each lesson's outputs reside in phases/<phase-number>-<phase-slug>/<lesson-number>-<lesson-slug>/outputs/. For example, phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/ contains the artifacts for lesson 87.

How are skill files differentiated from other markdown outputs?

Skill files must start with the literal prefix skill- followed by a kebab-case slug and the .md extension, such as skill-end-to-end-safety-gate.md. This distinguishes them from prompt templates (prompt-<slug>.md) and other documentation.

What enforces the naming conventions for lesson outputs?

The scripts/audit_lessons.py script automatically verifies that each lesson contains an outputs/ folder and checks that files follow the required naming patterns. Additionally, site/build.js relies on these conventions to generate the site data.

Can lessons reference outputs from other lessons programmatically?

Yes. Because every lesson uses the identical outputs/ folder name and consistent file prefixes, lessons can construct relative paths (e.g., ../../outputs/skill-<slug>.md) to import skills or read JSON reports from previous lessons in the curriculum.

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