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

> Discover how Agent Skills are managed, installed, and executed in compatible host environments. Learn about artifact management, staging directories, and manifest files for seamless operation.

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

---

**Agent Skills are managed as self-contained artifacts—either flat markdown files or directory bundles containing a [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) metadata file and supporting assets.

For each candidate, the system invokes `parse_frontmatter` from [`scripts/_lib.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.

```bash

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

### Host Integration Workflow

1.  **Manifest Loading**: The host reads [`manifest.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json) to enumerate all installed skills and filters by `name` or `tags`.
2.  **Parameter Extraction**: The host reads the [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) or [`run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run.py)) or shell script ([`run.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run.sh)) located within the bundle directory.

```python

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) scanning `phases/**/outputs` for [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) files and flat artifacts, with metadata extraction handled by `parse_frontmatter` in [`scripts/_lib.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json).
- **Execution** relies on hosts reading the manifest to locate skills, parsing [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py) scanner checks for two patterns: directories containing a [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/manifest.json) to locate the skill’s target directory, then read the [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) file within that directory. The front-matter in [`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md) contains execution parameters, while the manifest provides versioning and dependency information. The actual execution typically targets a [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run.py), or [`run.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run.sh) script contained within the bundle.