# How Reusable Artifacts Are Organized Across Lessons in AI Engineering From Scratch

> Discover how reusable artifacts are organized in the ai-engineering-from-scratch repository. Learn about standardized outputs, prompts, skills, and agent structures for modular AI development.

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

---

**Reusable artifacts in the ai-engineering-from-scratch curriculum are stored in lesson-specific `outputs/` directories and aggregated into repository-wide folders by type (prompts, skills, agents, and MCP servers), enabling modular cross-lesson reuse through consistent naming conventions and automated scripts.**

The `ai-engineering-from-scratch` repository structures its curriculum as a series of phases and lessons, where each lesson generates **reusable artifacts** stored in standardized locations. This organization ensures that prompts, skills, and agents created in one lesson can be seamlessly consumed by downstream lessons without code duplication, following the "Build It / Use It" philosophy documented in the repository.

## Lesson-Level Organization

Each lesson resides in its own directory under `phases/<phase-slug>/<lesson-slug>/` and contains an `outputs/` subdirectory for artifacts generated during that lesson. This isolation ensures lessons remain self-contained while producing shareable components.

### Artifact Type Subdirectories

Within each lesson's `outputs/` folder, files follow strict naming prefixes that indicate their function:
- **`prompt-*.md`** for LLM prompts
- **`skill-*.md`** for skill definitions
- **`agent-*.md`** for agent configurations
- **`mcp-servers-*.md`** for MCP server specifications

For example, the *Linear Algebra Intuition* lesson in phase 01 stores its tutor prompt at:

```

phases/01-math-foundations/01-linear-algebra-intuition/outputs/prompt-linear-algebra-tutor.md

```

## Repository-Wide Aggregation

To enable cross-lesson discovery, artifacts are copied from individual lesson directories into top-level `outputs/` folders categorized by type. The system maintains four centralized directories:
- `outputs/prompts/`
- `outputs/skills/`
- `outputs/agents/`
- `outputs/mcp-servers/`

### The Aggregation Pipeline

The [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) script automates this collection process. It scans phase and lesson directories, identifies artifacts by their filename prefixes, and distributes them to the appropriate repository-wide folders. This ensures the latest versions of all reusable components are centrally available for import.

```python

# scripts/install_skills.py – aggregates lesson artifacts to repo-wide locations

import pathlib
import shutil

root = pathlib.Path(__file__).parent.parent

for lesson in root.glob("phases/*/*"):
    if not lesson.is_dir():
        continue
    outputs_dir = lesson / "outputs"
    if not outputs_dir.exists():
        continue
    
    for artifact in outputs_dir.glob("*"):
        # Determine type from prefix (prompt-, skill-, agent-, etc.)

        name_parts = artifact.name.split("-")
        if len(name_parts) < 2:
            continue
            
        artifact_type = name_parts[0]
        dest_dir = root / "outputs" / f"{artifact_type}s"
        dest_dir.mkdir(parents=True, exist_ok=True)
        shutil.copy2(artifact, dest_dir / artifact.name)

```

## Consumption and Discovery

Downstream lessons and the curriculum website consume these centralized artifacts through automated discovery mechanisms that parse the standardized directory structure.

### Site Generation Integration

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script scans lesson-level `outputs/` directories to discover artifact links and generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) for the web UI. This creates a browsable index of all reusable components without manual registration, as the file system structure itself serves as the registry.

```javascript
// site/build.js – discovers artifacts for the web interface
const fs = require('fs');
const path = require('path');

const phasesDir = path.join(__dirname, '../phases');
const lessons = [];

// Scan phases for lesson outputs
fs.readdirSync(phasesDir).forEach(phase => {
  const phasePath = path.join(phasesDir, phase);
  fs.readdirSync(phasePath).forEach(lesson => {
    const outputsPath = path.join(phasePath, lesson, 'outputs');
    if (fs.existsSync(outputsPath)) {
      const artifacts = fs.readdirSync(outputsPath)
        .filter(f => f.endsWith('.md'))
        .map(f => ({
          type: f.split('-')[0], // prompt, skill, agent, etc.
          path: `phases/${phase}/${lesson}/outputs/${f}`
        }));
      lessons.push({ phase, lesson, artifacts });
    }
  });
});

```

## Practical Examples

### Creating an Artifact

Lessons generate artifacts by writing to their local `outputs/` directory. A Python script within a lesson might create a reusable prompt:

```python

# phases/01-math-foundations/01-linear-algebra-intuition/code/generate_prompt.py

prompt_content = """You are a linear algebra tutor. Explain vector addition 
using concrete examples from physics and computer graphics."""

with open("../outputs/prompt-linear-algebra-tutor.md", "w") as f:
    f.write(prompt_content)

```

### Installing Artifacts

After creation, the aggregation script copies the artifact to the central repository:

```bash

# Run the aggregation script to collect all lesson artifacts

python scripts/install_skills.py

# The file is now available at:

# outputs/prompts/prompt-linear-algebra-tutor.md

```

## Summary

- **Lesson-level storage**: Each lesson stores artifacts in `phases/<phase>/<lesson>/outputs/` with standardized naming prefixes.
- **Type-based organization**: Artifacts are categorized as prompts, skills, agents, or MCP servers based on filename conventions (`prompt-`, `skill-`, `agent-`, `mcp-servers-`).
- **Centralized aggregation**: The [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) script copies artifacts from lessons to repository-wide `outputs/` folders by type.
- **Automatic discovery**: The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script scans these directories to generate the curriculum interface without manual registration.
- **Cross-lesson reuse**: Downstream lessons import artifacts from the centralized directories rather than recreating functionality.

## Frequently Asked Questions

### What types of reusable artifacts does the repository support?

The repository supports four primary artifact types: **prompts** (LLM instruction templates), **skills** (reusable capability definitions), **agents** (autonomous agent configurations), and **MCP servers** (Model Context Protocol server specifications). Each type uses a distinct filename prefix to enable automatic categorization during aggregation.

### How does the aggregation script distinguish between different artifact types?

The [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) script parses filenames to identify artifact types, specifically looking for prefixes like `prompt-`, `skill-`, `agent-`, and `mcp-servers-`. It extracts the type from the first hyphen-separated segment of the filename and routes the file to the corresponding pluralized directory (`outputs/prompts/`, `outputs/skills/`, etc.).

### Can lessons in later phases access artifacts created in earlier phases?

Yes, lessons can access any artifact from the entire curriculum through the centralized `outputs/` directories. Because the aggregation pipeline copies all lesson artifacts to these top-level folders regardless of their origin phase, downstream lessons simply reference [`outputs/skills/skill-name.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/skills/skill-name.md) or [`outputs/prompts/prompt-name.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/prompts/prompt-name.md) to reuse components from any previous lesson.

### Where is the lesson structure contract documented?

The required structure for lessons and their `outputs/` directories is documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the *Lesson contract* section. This file specifies that every lesson must include an `outputs/` folder containing properly prefixed artifacts to ensure compatibility with the aggregation and site generation scripts.