How Reusable Artifacts Are Organized in the outputs Directory of ai-engineering-from-scratch

The rohitg00/ai-engineering-from-scratch curriculum stores every reusable artifact—prompts, skills, agents, and MCP servers—in a dual-layer hierarchy: per-lesson outputs/ folders for source files and a root-level outputs/ catalog with an index.json manifest for discovery and installation.

The ai-engineering-from-scratch repository provides a structured curriculum for building AI systems, with a specific convention for organizing reusable artifacts that ensures prompts, skills, and agents remain discoverable and portable. This article explains how the outputs directory structure works across both individual lessons and the repository root, enabling seamless integration into downstream workflows like Claude skills or LangChain prompts.

Per-Lesson outputs Folder Structure

Each lesson in the curriculum resides under phases/<NN>-<phase-name>/<NN>-<lesson-slug>/, where <NN> represents a zero-padded number. Inside every lesson folder, an outputs/ directory holds the artifacts generated by that specific lesson.

According to the lesson layout documentation in README.md (lines 89-97), this structure ensures that artifacts remain co-located with the content that produces them while maintaining clear boundaries between lessons.

Artifact Naming Conventions

Files within these directories follow a strict type-prefixed naming convention. For example:

• skill-<name>.md for skill definitions
• prompt-<name>.md for prompt templates
• agent-<name>.md for agent configurations

Each markdown file includes YAML front-matter identifying its type, name, phase, lesson, version, and description. This metadata enables automated parsing and categorization by the installation scripts.

Root-Level outputs Catalog

At the repository root, a consolidated outputs/ folder serves as a central registry. Unlike the per-lesson folders that contain actual content, this directory holds placeholder files (.gitkeep) for each artifact category—such as outputs/skills/.gitkeep—to preserve the directory structure in version control.

The index.json Inventory

The root outputs/index.json file acts as the canonical manifest of all discovered artifacts. This JSON file lists every artifact found across the curriculum, including totals per type and per phase. The file is generated programmatically and currently exists as an empty inventory in the repository, ready to be populated by the helper scripts.

Discovery and Installation with install_skills.py

The scripts/install_skills.py utility automates the process of scanning, filtering, and installing reusable artifacts from the distributed lesson structure into a target environment.

The discover_artifacts() Function

The core discovery logic resides in the discover_artifacts() function (lines 91-106), which walks the curriculum using the glob pattern PHASES_DIR.glob("*/[0-9][0-9]-*/outputs"). This pattern matches lesson directories across all phases, yielding structured Artifact objects containing metadata such as type, name, phase, and lesson identifiers.

The script parses the YAML front-matter of each markdown file found in these directories to build a complete inventory of available assets.

Installation Layouts

When copying artifacts to a user-specified target directory, the script supports three distinct layout strategies via the --layout parameter:

1. flat – Copies all files into a single directory without hierarchy
2. by-phase – Organizes files into subdirectories grouped by curriculum phase
3. skills – Creates a structure optimized for skill consumption by agents like Claude

The write_manifest() function (lines 200-221) handles the generation of the installation summary, writing a JSON file that summarizes totals per artifact type and phase.

Practical Examples

To list all skill artifacts without installing them:

python3 scripts/install_skills.py /tmp/dummy --type skill --dry-run

This command scans the phases/ directory and prints entries like:

[skill] agent-loop <- phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md

To programmatically load a prompt artifact's metadata:

from pathlib import Path
from scripts._lib import parse_frontmatter

prompt_path = Path(
    "phases/11-llm-engineering/01-prompt-engineering/outputs/prompt-engineering.md"
)
meta = parse_frontmatter(prompt_path.read_text())
print(meta["name"], meta["description"])

# Output: "prompt-engineering" "Prompt engineering techniques & patterns"

To install all artifacts into a flat directory structure:

mkdir -p ~/my-artifacts
python3 scripts/install_skills.py ~/my-artifacts --layout flat

This creates files like ~/my-artifacts/agent-loop.md and ~/my-artifacts/prompt-engineering.md, ready for import into downstream workflows such as Claude skills, LangChain prompts, or custom agents.

Summary

• The curriculum uses a dual-layer hierarchy: per-lesson outputs/ folders store source artifacts, while the root outputs/ directory maintains a central catalog.
• Artifacts follow a type-prefixed naming convention (e.g., skill-, prompt-, agent-) with YAML front-matter for metadata.
• The scripts/install_skills.py utility provides automated discovery via discover_artifacts() and supports three installation layouts: flat, by-phase, and skills.
• The outputs/index.json manifest offers a machine-readable inventory of all reusable assets across the curriculum.

Frequently Asked Questions

What file naming convention is used for artifacts in the outputs directory?

Files in the outputs directory use a type-prefixed format: skill-<name>.md, prompt-<name>.md, or agent-<name>.md. Each file contains YAML front-matter specifying the artifact's type, name, phase, lesson, version, and description, enabling automated parsing by the installation scripts.

How does the install_skills.py script discover reusable artifacts?

The script's discover_artifacts() function scans the curriculum using the glob pattern PHASES_DIR.glob("*/[0-9][0-9]-*/outputs") to locate all lesson output directories. It parses the YAML front-matter of each markdown file found to construct Artifact objects containing metadata about type, name, and location.

What installation layouts are supported when copying artifacts?

The install_skills.py script supports three layouts via the --layout parameter: flat (all files in one directory), by-phase (grouped by curriculum phase), and skills (optimized for Claude skill consumption). This flexibility allows integration with various downstream workflows and agent frameworks.

Where is the central manifest of all outputs directory artifacts stored?

The root-level outputs/index.json file serves as the central manifest, generated by the write_manifest() function in scripts/install_skills.py. This JSON file lists all discovered artifacts with totals per type and per phase, while the root outputs/ folder contains .gitkeep placeholders for each category to preserve directory structure.

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