How the 'Ship It' Step Works in AI Engineering From Scratch: From Code to Reusable Artifacts

The 'Ship It' step converts validated lesson code into portable artifacts stored in the outputs/ directory, enabling other lessons and external projects to import reusable prompts, skills, agents, or MCP servers through the repository's skills system.

The AI Engineering From Scratch curriculum organizes every lesson around a rigorous six-beat pipeline designed to maximize learning retention and code reusability. Understanding how the 'Ship It' step functions within this lesson progression is essential for both contributors creating new content and learners consuming existing lessons. This final stage ensures that working code does not remain trapped in tutorial notebooks but becomes a first-class building block for future projects.

What Is the 'Ship It' Step?

Every lesson in the repository follows a standardized pedagogical flow:

MOTTO → PROBLEM → CONCEPT → BUILD IT → USE IT → SHIP IT

The 'Ship It' beat represents the culmination of the lesson progression. While Build It focuses on authoring code and Use It emphasizes verification through testing, Ship It transforms that code into a reusable artifact. These artifacts live under each lesson's outputs/ directory and are designed to be completely portable, carrying no dependencies on the lesson's internal folder structure—only adhering to the public contract defined in the artifact's header.

Types of Artifacts Produced During 'Ship It'

During the Ship It phase, a lesson generates one or more standardized artifact types. Each artifact serves a distinct purpose in the broader ecosystem:

• Prompt (.md or .txt): A ready-to-paste prompt compatible with any LLM, allowing users to replicate the lesson's reasoning patterns in external environments.

• Skill (.md): A markdown file following the SKILL.md specification that can be installed via the repository's skills/ system, making the lesson's logic available as a callable module.

• Agent (.md, .py, or .ts): A minimal ReAct-style agent implementation that downstream agents can import and extend for complex workflows.

• MCP Server (.py or .ts): A lightweight Model Context Protocol server that exposes the lesson's functionality through a standardized API interface.

All artifacts are deliberately isolated from lesson internals. This portability ensures that other lessons—or users browsing the website—can copy-paste the artifact directly without resolving complex relative imports.

Implementation of the 'Ship It' Workflow

The Ship It step operates through five distinct phases enforced by the repository's tooling and CI pipeline.

1. Artifact Creation in outputs/

The lesson author creates a markdown file under the lesson's outputs/ directory. For example, in phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md, the file begins with a YAML front-matter block declaring metadata:

---
name: agent-loop
description: ReAct‑style loop for any tool list
phase: 14
lesson: 01
tags: [react, agent-loop, tools, stop-condition]
---

Following the front-matter, the file contains the actual implementation logic or prompt template that constitutes the shipable unit.

2. Documentation Reference

The lesson's docs/en.md file must reference the artifact in its dedicated Ship It section. For instance:

## Ship It

`outputs/skill-agent-loop.md` is a reusable skill that any agent you build can load to explain the ReAct loop and generate a correct reference implementation for any language or runtime.

This reference pattern appears consistently across lessons, ensuring students can locate deliverables quickly.

3. Validation via scripts/audit_lessons.py

The continuous integration pipeline runs scripts/audit_lessons.py to enforce artifact quality. This script validates that every outputs/*.md file:

• Contains a properly formatted front-matter block
• Adheres to the SKILL.md schema with required fields and valid markdown syntax
• Is explicitly referenced from the parent lesson's docs/en.md
• Can be parsed correctly by the site builder without rendering errors

4. Publication through site/build.js

When a pull request merges, the site/build.js script processes the outputs/ directory. It reads the front-matter from each markdown file, generates entries for the Artifacts section of the lesson webpage, and integrates the artifacts into the site's searchable navigation. The script automatically creates URLs linking directly to raw artifact files.

5. Artifact Consumption

End users interact with shipped artifacts through three primary methods:

• Direct Copy-Paste: Users copy prompts or code snippets directly from the website into their own notebooks or IDEs.
• Skill Installation: Using the universal CLI command npx skills add rohitg00/ai-engineering-from-scratch, the system registers all outputs/*.md skills into the user's local skill store, making them available via the learn command.
• Direct Import: Developers import MCP servers or agent implementations directly from the repository path (e.g., phases/14-agent-engineering/01-the-agent-loop/outputs/).

Code Examples from the Repository

Minimal Skill File Structure

The following excerpt from phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md demonstrates the required structure for a shipped skill:

---
name: agent-loop
description: ReAct‑style loop for any tool list
phase: 14
lesson: 01
tags: [react, agent-loop, tools, stop-condition]
---
Implement a minimal agent loop that:
- Accepts a message buffer,
- Calls a `ToolRegistry`,
- Enforces a turn‑budget,
- Emits a trace of Thought → Action → Observation.

Referencing Artifacts in Lesson Documentation

The docs/en.md file in the Agent-Loop lesson explicitly points to the shipped artifact:

## Ship It

`outputs/skill-agent-loop.md` is a reusable skill that any agent you build can load to explain the ReAct loop and generate a correct reference implementation for any language or runtime.

Installing Shipped Skills via CLI

Users can install the lesson's artifacts into their local environment using the skills system:

npx skills add rohitg00/ai-engineering-from-scratch

# The skill `agent-loop` becomes available for `learn` or direct invocation:

learn agent-loop

The CLI reads the outputs/skill-agent-loop.md file and registers the skill in the user's environment without requiring manual file management.

Key Files in the 'Ship It' Workflow

• phases/<phase>/<lesson>/outputs/skill-*.md: Stores the final shipable artifact (prompt, skill, agent definition, or MCP server).
• phases/<phase>/<lesson>/docs/en.md: Contains the Ship It section that documents and links to the artifact.
• scripts/audit_lessons.py: CI validator ensuring schema compliance and documentation linkage.
• site/build.js: Generates public-facing lesson pages that expose artifacts through the website interface.
• README.md: Displays the lesson flow diagram illustrating Ship It as the final beat in the six-stage pipeline.

Summary

• The 'Ship It' step is the sixth and final beat in the lesson progression pipeline, following Use It.
• Artifacts are stored in lesson-specific outputs/ directories as standalone markdown or code files.
• All artifacts require YAML front-matter metadata and must be referenced in the lesson's docs/en.md.
• The scripts/audit_lessons.py script enforces quality control through automated schema validation.
• Artifacts are published via site/build.js and consumable through copy-paste, CLI installation (npx skills add), or direct import.
• This system ensures AI Engineering From Scratch functions as a library of interoperable components rather than a linear tutorial.

Frequently Asked Questions

What file format must 'Ship It' artifacts use?

Shipped artifacts are typically markdown (.md) files for prompts and skills, though agents and MCP servers may use .py or .ts extensions. All markdown artifacts must include a YAML front-matter block declaring the name, description, phase, lesson, and tags fields to pass validation in scripts/audit_lessons.py.

How does the validation system ensure artifact quality?

The repository runs scripts/audit_lessons.py in CI to verify that every file in an outputs/ directory contains valid front-matter, follows the SKILL.md schema, and is referenced from the parent lesson's documentation. This prevents orphaned artifacts and guarantees that all shipped code meets the repository's formatting standards.

Can external projects use artifacts from AI Engineering From Scratch?

Yes. The artifacts are designed to be completely portable and do not rely on the lesson's internal folder layout. External projects can copy-paste prompts directly from the website, install skills via npx skills add rohitg00/ai-engineering-from-scratch, or import MCP servers directly from the repository paths listed in the outputs/ directories.

What is the difference between a Skill and an Agent artifact?

A Skill is a markdown file containing reusable logic or prompts that can be loaded by the skills system to augment an agent's capabilities. An Agent artifact is an executable implementation (often Python or TypeScript) that defines a complete ReAct-style agent loop ready for direct import and execution. Skills extend agents; agents consume skills.

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