Anthropic Skills Format Standard: A Technical Guide to Modular AI Agent Specifications

The Anthropic Skills format standard defines a lightweight, human-readable specification using a YAML-fronted Markdown file (SKILL.md) that declares agent capabilities, supported by optional helper scripts and on-demand asset loading to enable progressive context management across hundreds of skills.

The Anthropic Skills format standard provides a modular approach to extending Claude-based agents with external capabilities. Developed as an open specification by Anthropic in December 2025 and implemented in the ComposioHQ/awesome-claude-skills repository, this format enables developers to define what an AI agent should do, when to activate specific behaviors, and how to interact with external tools through a standardized directory structure and progressive loading mechanism.

Core Components of the Anthropic Skills Format Standard

Every skill in the ComposioHQ/awesome-claude-skills repository follows a strict convention centered on the SKILL.md file, with optional directories for executable scripts and static assets.

SKILL.md - The Central Specification File

At the heart of every skill sits SKILL.md, a Markdown file residing in the skill's root directory. According to the template-skill/SKILL.md implementation, this file contains two distinct sections: a YAML front-matter block for metadata and a free-form instructional body that guides the model's behavior.

YAML Front-Matter

The front-matter section uses standard YAML delimiters (---) to declare the skill's identity. It requires exactly two fields:

• name: The unique identifier for the skill
• description: A concise summary (approximately 100 tokens) consumed by the model at load-time

This metadata is the only portion of the skill loaded at session initialization, making it critical for the progressive loading architecture.

Instruction Body

Following the front-matter, the instruction body contains Markdown content—including sections, bullet points, tables, and inline references to auxiliary files. The specification recommends keeping this body under 5,000 tokens to maintain cost-effective, on-demand streaming when the skill becomes relevant to the conversation.

Optional Assets and Helper Scripts

Beyond the core SKILL.md, the format supports two optional directories that extend functionality without bloating initial context:

The scripts/ Directory

The scripts/ folder contains executable files (Python, Bash, or other languages) that the skill invokes via the tool-calling API. As seen in examples like mcp-builder/scripts/evaluation.py, these files remain unloaded until the model explicitly requests execution, minimizing context window consumption.

The references/ Directory

Large static assets such as PDFs, images, and data files reside in references/. The canvas-design/README.md example demonstrates how skills reference these assets on demand rather than including them in the initial prompt.

Progressive Loading Strategy

The Anthropic Skills format standard implements a crucial performance optimization known as progressive loading. At session initialization, the model receives only the YAML front-matter (names and short descriptions) for all available skills. When the model determines a skill is relevant to the current conversation, it streams the full SKILL.md body and any required auxiliary files.

This architecture enables a single agent to host hundreds of skills simultaneously without exceeding context window limits. As implemented in the ComposioHQ/awesome-claude-skills source code, the full instruction body and helper scripts are fetched only upon relevance determination, making the system scalable and cost-efficient.

Creating a Minimal Anthropic Skill

To implement the Anthropic Skills format standard, create a directory containing SKILL.md and optional helper scripts. Below is a complete, runnable example implementing a weather-fetching skill.

File structure:

my-weather-skill/
├── SKILL.md
└── scripts/
    └── get_weather.py

SKILL.md content:

---
name: weather-fetcher
description: Retrieve the current weather for a given city.
---

# Weather Fetcher Skill

When the user asks for weather, call the `get_weather` script with the city name.

```json
{
  "tool": "get_weather",
  "args": {
    "city": "{{city}}"
  }
}

The script returns a short weather summary that the model can incorporate into its response.

Helper script ([`scripts/get_weather.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/scripts/get_weather.py)):

```python
import sys, json, requests

def main():
    # Composio will pass arguments as JSON on stdin

    args = json.load(sys.stdin)
    city = args.get("city", "")
    # Simple OpenWeatherMap call (API key is injected by the runtime)

    resp = requests.get(
        "https://api.openweathermap.org/data/2.5/weather",
        params={"q": city, "appid": "<YOUR_API_KEY>"}
    )
    data = resp.json()
    summary = f"{city}: {data['weather'][0]['description']}, {data['main']['temp']}°C"
    print(json.dumps({"summary": summary}))

if __name__ == "__main__":
    main()

When Claude determines the skill is relevant, it streams the SKILL.md body, requests get_weather.py on demand, executes it via the tool-calling API, and embeds the returned summary into its response.

Ecosystem Compatibility and Open Standard Status

Anthropic published the Skills format as an open standard in December 2025, maintaining the specification at the official Anthropic/skills repository. The ComposioHQ/awesome-claude-skills implementation adheres verbatim to this specification, ensuring compatibility across Claude Code, Claude.ai, the Claude API, and third-party platforms including Cursor and Gemini CLI.

Summary

• The Anthropic Skills format standard centers on SKILL.md, a YAML-fronted Markdown file containing metadata and instructional content.
• Progressive loading ensures only skill names and short descriptions load initially, with full bodies and scripts fetched on-demand.
• Optional scripts/ and references/ directories extend functionality without consuming context window space until explicitly invoked.
• The specification supports hundreds of skills per agent while maintaining performance through strict token limits (~100 for front-matter, <5000 for bodies).
• Published as an open standard in December 2025, the format ensures cross-platform compatibility with Claude-based tools and third-party agents.

Frequently Asked Questions

What is the difference between SKILL.md and README.md in Anthropic Skills?

SKILL.md serves as the executable specification that the model consumes to determine behavior, containing YAML front-matter and instructional content. README.md provides human-facing documentation about the skill's purpose and usage but never executes or loads into the model's context during operation.

How does progressive loading work in the Anthropic Skills format?

Progressive loading streams only the YAML front-matter (name and description) to the model at session start. When the model identifies a skill as relevant to the user's request, it fetches the full SKILL.md body and any requested auxiliary files from scripts/ or references/, keeping the active context window minimal and cost-effective.

Are Anthropic Skills compatible with platforms other than Claude?

Yes. The format is an open standard compatible with Claude Code, Claude.ai, the Claude API, and third-party platforms such as Cursor and Gemini CLI. The ComposioHQ/awesome-claude-skills repository implements the official Anthropic specification, ensuring cross-platform portability.

What is the maximum recommended size for a skill's instruction body?

The specification recommends keeping the instruction body under 5,000 tokens to enable efficient on-demand loading. The YAML front-matter should remain concise at approximately 100 tokens, as the model loads this metadata for every available skill at session initialization.

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