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

> Learn how lesson outputs are organized in the phases directory of rohitg00/ai-engineering-from-scratch. Discover naming conventions for skills, prompts, and reports.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-06-09

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and the site generator [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skill-end-to-end-safety-gate.md) and [`gate_trace.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Generates the site's [`data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/data.js) by scanning `outputs/` directories throughout the `phases` folder, relying on the consistent `skill-` and `prompt-` prefixes to categorize artifacts.

The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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

```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

```javascript
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script validates compliance with these conventions.
- The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.