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

> Understand the 'Ship It' step in AI engineering. Convert lesson code into reusable artifacts like prompts and agents for easy import into other projects.

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

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md), the file begins with a YAML front-matter block declaring metadata:

```markdown
---
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must reference the artifact in its dedicated *Ship It* section. For instance:

```markdown

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

The continuous integration pipeline runs [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)
- Can be parsed correctly by the site builder without rendering errors

### 4. Publication through [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)

When a pull request merges, the [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md) demonstrates the required structure for a shipped skill:

```markdown
---
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file in the Agent-Loop lesson explicitly points to the shipped artifact:

```markdown

## 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:

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py): CI validator ensuring schema compliance and documentation linkage.
- [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js): Generates public-facing lesson pages that expose artifacts through the website interface.
- [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md).
- The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script enforces quality control through automated schema validation.
- Artifacts are published via [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).

### How does the validation system ensure artifact quality?

The repository runs [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.