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

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

# 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 script scans lesson-level outputs/ directories to discover artifact links and generate 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.

// 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:

# 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:

# 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 script copies artifacts from lessons to repository-wide outputs/ folders by type.
• Automatic discovery: The 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 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 or 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 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.

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