# What Does the outputs Directory Contain in AI Engineering from Scratch?

> Discover what the outputs directory holds in AI Engineering from Scratch. Find skill definitions, prompts, agent configs, and MCP specs organized for easy reuse. Learn more!

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

---

**The `outputs` directory in the AI Engineering from Scratch repository serves as a central hub for generated, reusable artifacts—including skill definitions, prompts, agent configurations, and MCP server specifications—organized under a top-level manifest and distributed across per-lesson subdirectories.**

The `rohitg00/ai-engineering-from-scratch` curriculum structures its content around practical, exportable components that learners can integrate into their own projects. The `outputs` directory houses these artifacts in two distinct layers: a root-level registry that catalogs available asset types, and lesson-specific folders that contain the actual authored files consumed by the site generator and downstream tooling.

## Top-Level Registry and Placeholders

The repository root contains an `outputs/` folder that functions as a discovery mechanism for the build system.

- **[`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json)** – A minimal manifest listing the four artifact categories: `prompts`, `skills`, `agents`, and `mcp_servers`. The site-generation scripts ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) parse this file to discover which assets are available for rendering in the documentation site.

- **Subdirectory placeholders** – The folders `outputs/skills/`, `outputs/prompts/`, `outputs/agents/`, and `outputs/mcp-servers/` currently contain only `.gitkeep` files. These placeholders ensure Git tracks the directories while allowing CI pipelines to populate them with compiled assets during automated builds.

## Per-Lesson Artifact Directories

Each lesson or certification module stores its specific deliverables inside an `outputs/` subdirectory within its own folder path. For example, `phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/` contains the exportable artifacts for that specific capstone.

These directories hold several standardized file types:

- **Skill Markdown files** (`skill-*.md`) – Human-readable definitions describing reusable capabilities. These files include YAML front-matter, detailed descriptions, lifecycle steps, aggregation tables, and trace structure documentation. The file [`phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md) illustrates this format, describing the End-to-End Safety Gate capability with references to accompanying data files.

- **Data artifacts** – Structured JSON or CSV files that accompany skills. The [`gate_trace.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/gate_trace.json) file in the safety-gate lesson stores example request traces and taxonomy fixtures referenced within the skill markdown.

- **Prompt files** (`prompt-*.md` or `.txt`) – Exported prompt templates for lessons focused on prompt engineering.

- **Agent definitions** (`agent-*.md`) – Configuration and behavior specifications for lessons that ship autonomous agents.

- **MCP-server specifications** (`mcp-server-*.md`) – Documentation for lessons exposing servers compliant with the Model Context Protocol (MCP).

Unlike build artifacts, these files are **authored directly by lesson contributors** and consumed by both the website builder ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) and validation scripts such as [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).

## Working with outputs Files Programmatically

You can interact with the `outputs` directory using standard file I/O operations. Below are practical examples for accessing the manifest, reading skill definitions, and loading associated data.

### Loading the Top-Level Manifest

```python
import json
from pathlib import Path

manifest_path = Path(__file__).parent.parent / "outputs" / "index.json"
with manifest_path.open() as f:
    manifest = json.load(f)

print(manifest["skills"])   # → []  (populated later by CI)

```

### Reading a Skill Definition

```python
skill_path = Path(
    "phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md"
)

with skill_path.open() as f:
    content = f.read()

print(content.splitlines()[0:5])   # shows the front-matter header

```

### Accessing Associated JSON Artifacts

```python
import json

trace_path = Path(
    "phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/gate_trace.json"
)

with trace_path.open() as f:
    traces = json.load(f)

print(traces["version"])   # → "1.0.0"

```

## Summary

- The `outputs` directory in `rohitg00/ai-engineering-from-scratch` stores **author-edited artifacts** rather than generated build files.
- **[`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json)** provides a machine-readable registry of artifact categories used by site-generation scripts.
- **Per-lesson `outputs/` folders** contain skill markdown, JSON data, prompts, agent definitions, and MCP-server specs that learners can import into their own codebases.
- The consistent layout (`skill-*.md`, [`gate_trace.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/gate_trace.json), etc.) supports automated auditing via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and website rendering via [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js).

## Frequently Asked Questions

### What is the purpose of [`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json)?

The [`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json) file acts as a central manifest that lists the four artifact categories: `prompts`, `skills`, `agents`, and `mcp_servers`. The site builder ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) reads this file to discover which asset directories exist, enabling automated generation of documentation pages without hardcoding paths.

### Why do the subdirectories contain only `.gitkeep` files?

The subdirectories (`outputs/skills/`, `outputs/prompts/`, etc.) use `.gitkeep` files to ensure Git tracks otherwise empty folders. This design allows the repository structure to exist in version control while remaining flexible for CI pipelines that may populate these directories with compiled or aggregated assets during build processes.

### How are skill markdown files structured?

Skill markdown files follow a standardized format including YAML front-matter, a detailed description of the capability, lifecycle steps, aggregation tables, and trace structures. They reference accompanying data files (like [`gate_trace.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/gate_trace.json)) and are authored directly by contributors in lesson-specific `outputs/` directories, making them both human-readable and parseable by downstream tooling.

### Can I use these artifacts in my own projects?

Yes. The artifacts in the `outputs` directory are designed as reusable components. You can copy skill definitions, prompts, or agent configurations directly from lesson folders into your own applications, or parse the JSON data files programmatically to import the structured specifications into your systems.