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

> Understand the Anthropic Skills format standard, a YAML-fronted Markdown spec for agent capabilities. Learn how it enables modular AI with progressive context management.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: deep-dive
- Published: 2026-08-30

---

**The Anthropic Skills format standard defines a lightweight, human-readable specification using a YAML-fronted Markdown file ([`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md), a Markdown file residing in the skill's root directory. According to the [`template-skill/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) content:

```yaml
---
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) body, requests [`get_weather.py`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) serves as the executable specification that the model consumes to determine behavior, containing YAML front-matter and instructional content. [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.