Agent Skills Specification Overview

The Agent Skills specification defines a standardized format for packaging AI agent instructions, scripts, and resources into reusable, discoverable modules. Skills enable AI agents like Claude to perform specialized tasks in a repeatable way by loading domain-specific knowledge on demand.

What is a Skill?

A skill is a folder containing:

SKILL.md - A markdown file with YAML frontmatter containing metadata and instructions
Bundled Resources (optional) - Scripts, reference documentation, and assets that support the skill

Skills teach AI agents how to complete specific tasks, whether that’s creating documents with brand guidelines, analyzing data using specific workflows, or automating personal tasks. The specification is designed to be:

Simple - Just a folder with a SKILL.md file and optional resources
Portable - Works across different AI platforms and implementations
Discoverable - Metadata helps agents decide when to use each skill
Efficient - Progressive disclosure loads only what’s needed

Core Concepts

Progressive Disclosure

Skills use a three-level loading system to minimize context usage:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - Loaded when skill triggers (<500 lines ideal)
Bundled resources - Loaded as needed (unlimited size, scripts can execute without loading)

This approach ensures agents have awareness of all available skills without overwhelming their context window.

Skill Triggering

AI agents decide whether to use a skill primarily based on the description field in the YAML frontmatter. The description should include:

What the skill does
When to use it (specific contexts, triggers, use cases)
What it enables the agent to accomplish

The description is the primary triggering mechanism - all “when to use” information goes in the description, not in the SKILL.md body.

Bundled Resources

Skills can include additional files organized by purpose:

scripts/ - Executable code for deterministic or repetitive tasks
references/ - Documentation loaded into context as needed
assets/ - Files used in output (templates, icons, fonts)

Bundled resources allow skills to:

Provide reusable scripts instead of having agents write code from scratch
Include large reference documentation without loading it all at once
Package templates and assets needed for output generation

Skill Structure Example

skill-name/
├── SKILL.md              # Required: metadata + instructions
└── bundled-resources/    # Optional
    ├── scripts/          # Executable code
    │   ├── helper.py
    │   └── validator.js
    ├── references/       # Documentation
    │   ├── aws.md
    │   └── gcp.md
    └── assets/           # Templates, fonts, etc.
        └── template.docx

Design Principles

Keep SKILL.md Concise

The SKILL.md body should ideally be under 500 lines. When approaching this limit:

Move detailed documentation to reference files
Add clear pointers in SKILL.md about when to read each reference
Include tables of contents for large reference files (>300 lines)

Explain the Why

Instructions should explain why things are important, not just what to do. Modern AI agents benefit from understanding the reasoning behind instructions, allowing them to adapt to edge cases and novel situations.

Use Imperative Form

Prefer imperative instructions:

## Report Structure

ALWAYS use this exact template:

# [Title]
## Executive Summary
## Key Findings
## Recommendations

Domain Organization

When a skill supports multiple frameworks or domains, organize by variant:

cloud-deploy/
├── SKILL.md              # Workflow + selection logic
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

The agent reads only the relevant reference file based on the user’s needs.

Specification Status

The full Agent Skills specification is maintained at agentskills.io/specification. The specification is designed to be implementation-agnostic and works with various AI platforms. Anthropic’s implementation for Claude is available at github.com/anthropics/skills, which includes:

Example skills across creative, technical, and enterprise domains
Production document creation skills (DOCX, PDF, PPTX, XLSX)
Skill creation and testing tools
Templates for building new skills

Next Steps

SKILL.md Format

Learn the structure and syntax of SKILL.md files

Metadata Schema

Understand the YAML frontmatter schema

Loading System

Explore the three-level progressive disclosure system

Creating Skills

Build your first skill

Specification

​What is a Skill?

​Core Concepts

​Progressive Disclosure

​Skill Triggering

​Bundled Resources

​Skill Structure Example

​Design Principles

​Keep SKILL.md Concise

​Explain the Why

​Use Imperative Form

​Domain Organization

​Specification Status

​Next Steps