# How the Agent Skills Specification Works: A Complete Technical Guide > Discover how the Agent Skills specification works. This guide details the package format enabling Claude to discover and execute specialized capabilities efficiently, keeping context windows small. Learn more today! - Repository: [Anthropic/skills](https://github.com/anthropics/skills) - Tags: deep-dive - Published: 2026-02-16 --- **The Agent Skills specification defines a minimal, self-describing package format that uses three-layer progressive disclosure to keep context windows small while enabling Claude to discover and execute specialized capabilities on demand.** The Agent Skills specification is the standardized protocol that powers extensible capabilities in the `anthropics/skills` repository. This lightweight format allows developers to package domain-specific instructions, executable scripts, and reference materials into portable units that agents can load dynamically without bloating the context window. ## Core Components of the Agent Skills Specification A valid skill package is simply a folder containing three distinct layers of information, each loaded only when necessary. ### YAML Front-Matter and Metadata Every skill begins with YAML front-matter in the [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) file containing a `name` and `description`. According to the specification in [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md), this metadata remains **always in-context**, allowing the agent to decide when to trigger the skill without loading the full instruction set. ### The SKILL.md Instruction Body The body of [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) contains the procedural steps, examples, and logic that guide the agent's behavior. This content is loaded **only after** the skill is selected based on the metadata match, keeping the active context minimal until the capability is actually needed. ### Optional Bundled Resources Skills may include three optional directories that are loaded lazily: - **`scripts/`** – Executable code (Python, bash, etc.) that the agent can run - **`references/`** – Data files, schemas, or documentation referenced by the skill body - **`assets/`** – Binary files like images or templates used during execution These resources are read **only when** the [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body explicitly references them, implementing the progressive disclosure pattern. ## Progressive Disclosure Architecture The Agent Skills specification implements a **three-layer loading** strategy designed to minimize context window usage while maximizing available capabilities. 1. **Metadata Layer** – Only the `name` and `description` from the YAML front-matter are visible to the agent during skill discovery 2. **Body Layer** – Upon triggering, the full [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) content loads into context 3. **Resource Layer** – Individual files from `scripts/`, `references/`, or `assets/` load only when referenced by the active body This architecture is documented in [`skills/skill-creator/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) under the "Progressive Disclosure Design Principle" section, which explains how this approach allows skills to contain arbitrarily large reference materials without impacting performance until needed. ## File Structure and Key Implementation Files The `anthropics/skills` repository contains the canonical specification and reference implementations at specific paths: - **[`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md)** – The official specification document, pointing to the canonical online version at - **[`skills/skill-creator/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)** – Comprehensive guide covering skill anatomy, progressive disclosure principles, and best practices - **[`skills/skill-creator/scripts/init_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py)** – CLI tool that scaffolds a new skill directory with the correct layout - **[`skills/skill-creator/scripts/package_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/package_skill.py)** – Validation and packaging tool that creates `.skill` archives - **[`template/SKILL.md`](https://github.com/anthropics/skills/blob/main/template/SKILL.md)** – Minimal skeleton template used by the initialization script - **`skills/*/SKILL.md`** – Real-world implementation examples (e.g., [`skills/pdf/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md)) ## Practical Example: Creating and Packaging a Skill Below is a complete workflow demonstrating how to create, validate, and package a skill using the reference implementation tools. ```bash # 1️⃣ Initialise a fresh skill directory python skills/skill-creator/scripts/init_skill.py my-pdf-rotator --path ./my-pdf-rotator # 2️⃣ Add a reusable Python script to scripts/rotate_pdf.py # (edit the generated file directly with your rotation logic) # 3️⃣ Edit the front-matter in my-pdf-rotator/SKILL.md # --- # name: pdf-rotator # description: Rotate PDF files by a given angle. Use when a user asks to rotate a PDF. # --- # # # Rotate a PDF # Run `scripts/rotate_pdf.py ` to produce a rotated file. # 4️⃣ Validate and bundle the skill into a .skill archive python skills/skill-creator/scripts/package_skill.py ./my-pdf-rotator ./dist ``` This example illustrates the complete lifecycle: [`init_skill.py`](https://github.com/anthropics/skills/blob/main/init_skill.py) creates the required folder layout, the `description` field enables automatic skill discovery, and [`package_skill.py`](https://github.com/anthropics/skills/blob/main/package_skill.py) validates the front-matter and structure before producing the final archive. ## Summary - The **Agent Skills specification** defines a minimal, self-describing package format for extending agent capabilities without bloating context windows. - **Three-layer progressive disclosure** loads only metadata during discovery, the full [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body upon triggering, and bundled resources only when referenced. - **Required structure** includes YAML front-matter with `name` and `description`, plus the instruction body; optional `scripts/`, `references/`, and `assets/` directories support complex workflows. - **Reference implementation** in `anthropics/skills` provides the canonical spec at [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md), scaffolding tools at `skills/skill-creator/scripts/`, and real-world examples in `skills/*/SKILL.md`. ## Frequently Asked Questions ### What is the minimum required structure for a valid Agent Skill? A valid skill requires only a single [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) file containing YAML front-matter with `name` and `description` fields, followed by the instruction body. While optional directories like `scripts/`, `references/`, and `assets/` are supported for complex use cases, the specification mandates only the metadata and body content to maintain the progressive disclosure contract. ### How does the Agent Skills specification prevent context window bloat? The specification implements **progressive disclosure** through three distinct loading layers. First, only the YAML front-matter (name and description) remains in-context during skill discovery. Second, the full [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body loads only after the skill is triggered. Third, bundled resources from `scripts/`, `references/`, or `assets/` are read only when explicitly referenced by the active body, ensuring arbitrarily large skills don't impact performance until needed. ### Where can I find the official Agent Skills specification and tools? The canonical specification document lives at [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md) in the `anthropics/skills` repository, which references the live specification at . For implementation tools, use [`skills/skill-creator/scripts/init_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py) to scaffold new skills and [`skills/skill-creator/scripts/package_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/package_skill.py) to validate and bundle them into `.skill` archives. Real-world implementation examples are available in `skills/*/SKILL.md` directories throughout the repository. ### What is the difference between the SKILL.md body and bundled resources? The [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body contains the procedural instructions, examples, and logic that guide the agent's behavior, loaded immediately upon skill triggering. **Bundled resources** are external files stored in `scripts/`, `references/`, or `assets/` that are loaded **lazily** only when the [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body explicitly references them. This separation allows skills to include large codebases or datasets without keeping them in-context until execution requires them.