# How install_skills.py Installs Curriculum Artifacts: A Complete Guide

> Learn how the install_skills.py script installs curriculum artifacts. This guide details artifact extraction, copying, and configuration for your AI engineering projects.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-21

---

**The [`install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py) script is a command-line utility that extracts skill, prompt, and agent markdown artifacts from the curriculum's `phases/**/outputs` folders and copies them into a user-specified target directory with configurable layouts and filtering.**

The [`install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py) script in the `rohitg00/ai-engineering-from-scratch` repository automates the extraction and installation of curriculum artifacts. This utility processes markdown files containing YAML front-matter and organizes them into reusable skill bundles for downstream consumption.

## The Four-Stage Installation Pipeline

The script operates through a logical pipeline defined in [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py). Each stage transforms the raw curriculum files into structured, installable outputs.

### Stage 1: Discovery with discover_artifacts()

The `discover_artifacts()` function walks every `phases/*/outputs` directory to locate source files. It filters for markdown files whose names start with `skill-`, `prompt-`, or `agent-`, then reads each file and parses the YAML front-matter using `_lib.parse_frontmatter`.

This stage yields **Artifact** objects containing:
- Type, name, phase, and lesson identifiers
- Version and description metadata
- Tags and source file paths

*Source:* lines 94-136 of [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py).

### Stage 2: Filtering with filter_artifacts()

The `filter_artifacts()` function applies user-specified criteria to the discovered artifacts. It supports three filter dimensions:

- **`--type`**: Restrict to `skill`, `prompt`, `agent`, or `all`
- **`--phase`**: Numeric phase ID (e.g., `7`)
- **`--tag`**: Specific tag string to match

Only artifacts satisfying all active filters proceed to the planning stage.

*Source:* lines 139-154 of [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py).

### Stage 3: Planning with build_plan()

The `build_plan()` function maps each selected artifact to a destination path based on the chosen **layout strategy**:
- **`flat`**: All files in the target root
- **`by-phase`**: Organized into phase subdirectories
- **`skills`**: Hierarchical skill-based structure (default)

This stage detects file collisions—when two artifacts target the same destination path. Unless `--force` is enabled, collisions are recorded as errors. The plan consists of `(artifact, destination)` tuples plus collision tracking.

*Source:* lines 168-191 of [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py).

### Stage 4: Execution and Manifest Generation

The final stage executes the installation plan and records metadata:

**`apply_plan()`** creates parent directories as needed and copies each source markdown to its computed destination. If `--dry-run` is specified, the script reports the plan without writing files.

**`write_manifest()`** generates a [`manifest.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json) in the target root containing:
- Every installed artifact with its target path, type, phase, and tags
- Aggregated statistics grouped by type and phase

*Source:* lines 194-226 and 229-267 of [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py).

## Command-Line Interface and Usage Examples

The script exposes an `argparse` interface in `main()` (lines 288-292) that supports the following workflow patterns.

Install default skill artifacts using the `skills` layout:

```bash
python3 scripts/install_skills.py /path/to/target

```

Install all prompts for phase 7 using flat layout with overwrite enabled:

```bash
python3 scripts/install_skills.py /tmp/out --type prompt --phase 7 --layout flat --force

```

Preview agent artifacts without writing files:

```bash
python3 scripts/install_skills.py ./tmp --type agent --dry-run

```

Generate a JSON manifest for core-tagged artifacts only:

```bash
python3 scripts/install_skills.py ./out --tag core --json

```

The script exits with status `0` on success or `1` on errors such as no matching artifacts or unresolved collisions.

## Key Implementation Files

- **[`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py)** – Main driver implementing the four-stage pipeline
- **[`scripts/_lib.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/_lib.py)** – Helper module providing `parse_frontmatter()` for YAML extraction
- **`phases/**/outputs/*.md`** – Source markdown artifacts processed by the script

## Summary

- **Discovery**: The `discover_artifacts()` function scans `phases/*/outputs` for files prefixed with `skill-`, `prompt-`, or `agent-`, parsing YAML front-matter into structured objects.
- **Filtering**: The `filter_artifacts()` function applies `--type`, `--phase`, and `--tag` constraints to refine the selection.
- **Planning**: The `build_plan()` function maps artifacts to destinations using `flat`, `by-phase`, or `skills` layouts while detecting collisions.
- **Execution**: The `apply_plan()` and `write_plan()` functions copy files and generate [`manifest.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json), respecting `--dry-run` and `--force` flags.
- **Integration**: The script depends on [`scripts/_lib.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/_lib.py) for front-matter parsing and exits with standard Unix codes (0 for success, 1 for error).

## Frequently Asked Questions

### What file types does install_skills.py handle?

The script processes markdown files (`.md`) from `phases/**/outputs` directories that begin with the prefixes `skill-`, `prompt-`, or `agent-`. Each file must contain valid YAML front-matter describing the artifact's metadata, which the script extracts using `_lib.parse_frontmatter`.

### How do I prevent file collisions when running install_skills.py?

File collisions occur when two artifacts map to the same destination path. By default, the script records these as errors and exits with status 1. To overwrite existing files, use the `--force` flag. Alternatively, choose a different `--layout` option (such as `by-phase` instead of `flat`) to ensure unique paths.

### What is the difference between the layout options in install_skills.py?

The `--layout` parameter controls directory structure: `flat` places all files in the target root, `by-phase` organizes artifacts into subdirectories by phase number, and `skills` (the default) uses a hierarchical structure optimized for skill-based consumption. The `skills` layout is recommended for curriculum bundles.

### Where does install_skills.py store installation metadata?

After successful execution, the script writes a [`manifest.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json) file to the target directory root. This JSON file contains an array of all installed artifacts with their metadata (type, phase, tags, target paths) plus statistical aggregations by type and phase, enabling traceability and verification of the installation.