How the outputs/ Directory Works for Lessons (Prompts & Skills)

The outputs/ directory in rohitg00/ai-engineering-from-scratch stores reusable markdown skill files and JSON runtime artifacts for each lesson, serving as a version-controlled bridge between documentation, demo code, and downstream consumption.

The outputs/ folder follows a strict contract across every lesson in the rohitg00/ai-engineering-from-scratch curriculum. It houses both reference artifacts (immutable skill descriptions) and runtime results (generated metrics and traces), creating a reproducible pipeline for AI engineering assets. Understanding this directory structure is essential for navigating the curriculum and reusing prompt patterns across projects.

What Lives in the outputs/ Directory

Every lesson’s outputs/ folder contains two distinct categories of files that serve different purposes in the learning workflow.

Skill Markdown Files

Files matching the skill-*.md pattern contain reusable knowledge deliverables for the lesson. These markdown files describe prompt patterns, safety policies, pipeline descriptions, or architectural decisions in a format that downstream lessons can import verbatim. For example, phases/11-llm-engineering/01-prompt-engineering/outputs/skill-prompt-patterns.md defines reusable prompt engineering patterns that later capstone projects reference directly.

JSON Reports and Model Artifacts

Runtime demo scripts write concrete results to *.json, .safetensors, or .jsonl files. The code/main.py script in each lesson generates these files to capture metrics, model traces, or evaluation cards. For instance, phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/gate_trace.json contains a trace of every request processed by the safety gate demonstration, allowing learners to compare their generated results against the reference implementation.

How Lessons Reference outputs/ Artifacts

The curriculum establishes explicit linkages between documentation, code, and the artifacts stored in outputs/.

Documentation Linkage

Each lesson’s docs/en.md contains a dedicated section, typically labeled "Deliverable," that points to the exact path within outputs/. This creates a discoverable contract where learners can locate the skill file without searching the repository. The documentation treats these paths as immutable references, ensuring that external projects can reliably import specific curriculum versions.

Runtime Generation and Comparison

When you execute a lesson’s code/main.py, the script writes its results into the same outputs/ directory that houses the reference files. This pattern enables direct diff comparisons between your generated artifacts and the checked-in references. Because the files are version-controlled, they serve as a source of truth for what correct output should look like.

Downstream Consumption

Later lessons in the curriculum import artifacts from earlier outputs/ directories by relative path. The "Safety Gate" capstone lesson, for example, reads outputs/gate_trace.json from its own directory as input to its evaluation step. Similarly, prompt injection detection skills located at phases/19-capstone-projects/83-prompt-injection-detector/outputs/skill-prompt-injection-detector.md are imported verbatim by subsequent safety lessons.

Working with outputs/ Artifacts in Python

The repository expects learners to programmatically consume these files for extension and integration tasks.

Loading a Skill Markdown File

You can load any skill file as a string template for reuse in your own pipelines:

from pathlib import Path

# Path to a lesson's skill artifact

skill_path = Path(
    "phases/11-llm-engineering/01-prompt-engineering/outputs/skill-prompt-patterns.md"
)

# Read the skill (the markdown describes a reusable prompt pattern)

with skill_path.open(encoding="utf-8") as f:
    prompt_skill = f.read()

print("Loaded skill snippet:")
print(prompt_skill[:200])      # show the first 200 characters

Consuming JSON Runtime Reports

Analyze the concrete results generated by demo scripts to understand model behavior:

import json
from pathlib import Path

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

# The demo script writes this file; we can now analyse it

with report_path.open() as f:
    trace = json.load(f)

# Simple aggregation: count how many requests were flagged as unsafe

unsafe = sum(1 for r in trace if r["violation"])
print(f"Unsafe requests: {unsafe} / {len(trace)}")

Using Skills as Jinja2 Templates

Many skill files contain templated content that you can render with custom variables:

from jinja2 import Template
import pathlib

skill_md = pathlib.Path(
    "phases/11-llm-engineering/01-prompt-engineering/outputs/skill-prompt-patterns.md"
).read_text()

# Suppose the markdown contains a Jinja-style placeholder {{task}}

tmpl = Template(skill_md)
custom_prompt = tmpl.render(task="Summarize the following article")
print(custom_prompt)

Key File Paths in the Repository

Understanding the specific locations of these artifacts helps navigate the curriculum structure:

• phases/11-llm-engineering/01-prompt-engineering/outputs/skill-prompt-patterns.md – Reusable prompt patterns for the Prompt Engineering lesson.
• phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/gate_trace.json – Trace of every request processed by the safety gate demo.
• phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md – Explains the lesson's purpose and which outputs/ files are generated.
• phases/19-capstone-projects/87-end-to-end-safety-gate/code/main.py – Runs the end-to-end safety gate and writes its JSON trace to outputs/.
• phases/19-capstone-projects/83-prompt-injection-detector/outputs/skill-prompt-injection-detector.md – Describes the rule format for a prompt-injection detector.
• outputs/index.json – Catalog of all top-level output artifacts across the repository used by the site builder.

Summary

• The outputs/ directory serves as the artifact hub for every lesson in the curriculum, storing both markdown skills and generated data files.
• Skill files (skill-*.md) act as version-controlled, reusable knowledge units that downstream lessons import by path.
• JSON reports capture runtime metrics from code/main.py execution, enabling comparison against reference implementations.
• The docs/en.md file in each lesson explicitly links to its outputs/ artifacts, creating a discoverable contract for learners.
• All artifacts are checked into version control, making them immutable references for reproducible AI engineering workflows.

Frequently Asked Questions

What is the difference between a skill file and a JSON report in the outputs/ directory?

Skill files are markdown documents describing reusable concepts, patterns, or policies that you can copy into your own projects. JSON reports are machine-generated artifacts created when you run the lesson’s code/main.py script, containing specific metrics, traces, or evaluation results for that lesson’s demonstration.

How do I know which outputs/ files a specific lesson generates?

Consult the lesson’s docs/en.md file, which contains a "Deliverable" section pointing to the exact paths within outputs/. This documentation explicitly lists whether the lesson produces a skill markdown file, a JSON trace, or model artifacts like .safetensors files.

Can I modify the files in the outputs/ directory?

While you can modify files locally, the curriculum treats the checked-in versions in outputs/ as immutable references. When you run code/main.py, the script typically writes to the same outputs/ directory, allowing you to compare your generated results against the reference versions without altering the original skill files.

How do downstream lessons import skills from previous outputs/ directories?

Downstream lessons import skills using standard Python file I/O with relative paths. For example, a later capstone project might use Path("phases/11-llm-engineering/01-prompt-engineering/outputs/skill-prompt-patterns.md").read_text() to load a prompt pattern, or parse JSON files from previous safety lessons to build composite evaluation pipelines.

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