What are skills?

Skills were originally introduced by Anthropic. The open format and official specification live at agentskills.io. At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.

├── SKILL.md            # Required: instructions + metadata
├── scripts/            # Optional: executable code
├── references/         # Optional: documentation
└── assets/             # Optional: templates, resources

How skills work

Skills use progressive disclosure to manage context efficiently. Rather than loading everything at once, agents pull in skill content only when needed.

Discovery

At startup, agents load only the name and description of each available skill — just enough to know when it might be relevant. This keeps the initial context window small.

Activation

When a user's task matches a skill's description, the agent reads the full SKILL.md instructions into context. The description acts as a trigger — write it to clearly describe when the skill should be used.

Execution

The agent follows the instructions in SKILL.md, optionally loading referenced files or executing bundled scripts as needed. A well-written skill tells the agent exactly when and how to use these extra resources.

Anatomy of a skill

The SKILL.md file

Every skill starts with YAML frontmatter (metadata) and a Markdown body (instructions):

---
name: weather
description: Get current weather and forecasts (no API key required).
license: MIT
metadata:
  author: sundial
  version: "1.0"
---

# Weather

Two free services, no API keys needed.

## wttr.in (primary)

```bash
curl -s "wttr.in/London?format=3"
```

## Open-Meteo (fallback)

```bash
curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
```

The Markdown body has no required structure. Write whatever instructions your agent needs: workflows, code blocks, examples, guardrails.

References

The references/ directory holds documentation the agent reads on demand. Your SKILL.md should tell the agent when to read these files:

## References

- `references/getting-started.md` (setup and basic usage)
- `references/examples.md` (example workflows)

Scripts

The scripts/ directory holds executable helpers. The agent uses its tool-calling abilities (Bash, Python, etc.) to run them:

#!/usr/bin/env python3
"""Generate an image using OpenAI's API."""
import sys, os
from openai import OpenAI
...

Why skills?

• Self-documenting — A skill author or user can read a SKILL.md and understand what it does. Easy to audit and improve.
• Portable — Skills are just files. Version them in Git, share them as zips, push them to a registry. They work with any compatible agent.
• Composable — Use multiple skills in one project. A research workflow might useweb-search, pdf-to-text, and citations together.
• Reusable — Build a skill once, deploy it across multiple agent products. The same github skill works in Claude Code, Codex, and Sundial.

Next steps