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

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 – A minimal manifest listing the four artifact categories: prompts, skills, agents, and mcp_servers. The site-generation scripts (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 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 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) and validation scripts such as 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

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

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

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 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, etc.) supports automated auditing via scripts/audit_lessons.py and website rendering via site/build.js.

Frequently Asked Questions

What is the purpose of outputs/index.json?

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

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