How install_skills.py Installs Curriculum Artifacts: A Complete Guide

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

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.

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.

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

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:

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

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

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

Preview agent artifacts without writing files:

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

Generate a JSON manifest for core-tagged artifacts only:

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 – Main driver implementing the four-stage pipeline
• 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, respecting --dry-run and --force flags.
• Integration: The script depends on 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 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.

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