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

> Discover how reusable artifacts like prompts skills and agents are organized in the ai-engineering-from-scratch outputs directory using a dual-layer hierarchy and index.json manifest.

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

---

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

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

```

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

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

```

To programmatically load a prompt artifact's metadata:

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

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json) file serves as the central manifest, generated by the `write_manifest()` function in [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.