How Agent Skills Are Discovered, Installed, and Executed in Compatible Host Environments

Agent Skills are managed as self-contained artifacts—either flat markdown files or directory bundles containing a SKILL.md front-matter file—that are discovered by traversing the lesson tree, installed atomically via a staging directory approach, and executed by compatible hosts through a generated manifest.json file.

In the rohitg00/ai-engineering-from-scratch repository, the skill management system treats every capability as a portable artifact. This architecture allows AI agents, educational notebooks, and Claude-based runtimes to discover curriculum capabilities, install them safely into arbitrary environments, and execute them using standardized metadata conventions.

Skill Discovery in the Curriculum Tree

The discovery process begins in scripts/install_skills.py, which walks the phases/**/outputs directory structure to identify valid skill artifacts. The scanner detects two distinct patterns:

• Flat artifacts: Individual markdown files named skill-<name>.md (or prompt-…, agent-… variants).
• Skill bundles: Directories identified by a skill name containing a SKILL.md metadata file and supporting assets.

For each candidate, the system invokes parse_frontmatter from scripts/_lib.py to extract YAML front-matter fields including name, description, version, tags, phase, and lesson. The helper function derive_phase_lesson automatically infers phase and lesson numbers from the file path. For example, a skill located at phases/13-tools-and-protocols/24-skill-discovery/outputs/skill-catalog-builder/SKILL.md maps to phase 13, lesson 24.

Installing Skill Bundles and Flat Artifacts

Once discovery completes, the installation engine builds a deployment plan via build_plan. This plan maps each Artifact object to a target location based on the requested layout strategy: flat, by-phase, or skills.

Atomic Bundle Installation

For skill bundles, the install_bundle function creates a temporary staging directory and performs a race-safe copy using _open_bundle_directory and _open_bundle_file with appropriate file flags. After validate_skill_bundle confirms the integrity of the contents, the system atomically swaps the staged directory into its final destination. This prevents partial installations in concurrent environments.

For flat artifacts, install_flat_artifact handles single-file copies using _open_flat_artifact with similar safety guarantees.

Manifest Generation

Every installation writes a manifest.json file alongside the deployed artifacts via write_manifest. This manifest records critical metadata for each skill:

• Original source path and target installation path
• Artifact type (skill, prompt, or agent)
• Version, tags, and phase/lesson identifiers
• For bundles, a complete list of contained files

Because the manifest uses relative paths, host environments can relocate the entire skill collection without breaking internal references.

# Discover and install all skill bundles into ./my-skills using the "skills" layout

python3 scripts/install_skills.py ./my-skills --type skill --layout skills

# Output: summary report and ./my-skills/manifest.json

Executing Skills in Compatible Host Environments

A compatible host environment—whether a Claude-based agent runtime, an educational Jupyter notebook, or a custom AI tool—consumes skills through the manifest.json schema.

Host Integration Workflow

1. Manifest Loading: The host reads manifest.json to enumerate all installed skills and filters by name or tags.
2. Parameter Extraction: The host reads the SKILL.md front-matter to obtain execution parameters, including entry-point scripts and required asset paths.
3. Runtime Execution: The host runs the skill’s entry point, typically a Python script (main.py or run.py) or shell script (run.sh) located within the bundle directory.

# Load the manifest in a host environment

import json
import pathlib

manifest = json.loads((pathlib.Path("./my-skills") / "manifest.json").read_text())
for skill in manifest["artifacts"]:
    if skill["type"] == "skill":
        print(f"Skill {skill['name']} (v{skill['version']}) → {skill['target']}")

# Execute a specific skill (example: release-gate)

skill_dir = pathlib.Path("./my-skills") / "release-gate"

# Run the entry point script

python3 "$skill_dir"/run.py   # or python3 "$skill_dir"/main.py

Summary

• Discovery occurs via scripts/install_skills.py scanning phases/**/outputs for SKILL.md files and flat artifacts, with metadata extraction handled by parse_frontmatter in scripts/_lib.py.
• Installation uses atomic staging operations through install_bundle and install_flat_artifact, supporting three layout modes (flat, by-phase, skills) and generating a comprehensive manifest.json.
• Execution relies on hosts reading the manifest to locate skills, parsing SKILL.md for configuration, and running entry-point scripts within the bundle directories.
• The system validates bundles via validate_skill_bundle and ensures safe concurrent access through _open_bundle_directory and _open_bundle_file primitives.

Frequently Asked Questions

How does the discovery script differentiate between skill bundles and flat artifacts?

The scripts/install_skills.py scanner checks for two patterns: directories containing a SKILL.md file (treated as bundles) and individual markdown files matching naming conventions like skill-<name>.md (treated as flat artifacts). Both types undergo front-matter parsing via parse_frontmatter from scripts/_lib.py to extract metadata, but only bundles trigger the recursive copy logic in install_bundle.

What prevents corrupted installations if the process is interrupted?

The installation uses an atomic staging pattern. install_bundle writes to a temporary directory first, validates the contents with validate_skill_bundle, then performs an atomic move to the final destination. Flat artifacts use _open_flat_artifact with safe write flags. This ensures that incomplete writes never appear in the target directory, and the manifest.json is only written after all artifacts are successfully deployed.

Can I install skills into an existing project structure without conflicts?

Yes. The build_plan function supports three layout strategies: flat (all files in one directory), by-phase (organized by curriculum phase), and skills (organized by skill name). Host environments locate skills through the manifest.json file, which records relative paths, allowing the skill collection to function regardless of where it resides in the filesystem.

What file should a host read to determine how to execute a skill?

The host should first read manifest.json to locate the skill’s target directory, then read the SKILL.md file within that directory. The front-matter in SKILL.md contains execution parameters, while the manifest provides versioning and dependency information. The actual execution typically targets a main.py, run.py, or run.sh script contained within the bundle.

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