How the Agent Skills Specification Works: A Complete Technical Guide

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 file containing a name and description. According to the specification in 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 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 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 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 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 – The official specification document, pointing to the canonical online version at https://agentskills.io/specification
• skills/skill-creator/SKILL.md – Comprehensive guide covering skill anatomy, progressive disclosure principles, and best practices
• 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 – Validation and packaging tool that creates .skill archives
• template/SKILL.md – Minimal skeleton template used by the initialization script
• skills/*/SKILL.md – Real-world implementation examples (e.g., 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.

# 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 <path> <angle>` 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 creates the required folder layout, the description field enables automatic skill discovery, and 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 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, 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 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 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 in the anthropics/skills repository, which references the live specification at https://agentskills.io/specification. For implementation tools, use skills/skill-creator/scripts/init_skill.py to scaffold new skills and 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 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 body explicitly references them. This separation allows skills to include large codebases or datasets without keeping them in-context until execution requires them.

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