# Agent Skills (SKILL.md)

> VI: https://5ac.vn/wiki/agent-skills/ · EN: https://5ac.vn/en/wiki/agent-skills/ · lang: en · spec_as_of 2026-10-18 (spec unversioned) · cluster C4

A folder built around a SKILL.md file that agents load in three stages (discovery, activation, execution) to add portable specialist know-how.

---
## Definition

Agent Skills is an open format for giving an agent specialist know-how as a folder built around one SKILL.md file: the frontmatter declares name and description, the body carries instructions, and scripts or reference files sit alongside. The agent reads the metadata at startup and loads the full instructions only when a task actually matches.

## Mechanism

Skills load progressively, so detail enters the context window only when the task needs it and keeping many skills installed stays cheap.

| Stage | What the agent loads | Context cost |
| --- | --- | --- |
| Discovery | name and description of every skill at startup | about 100 tokens per skill |
| Activation | the whole SKILL.md body once a description matches | recommended under 5,000 tokens |
| Execution | scripts, references, assets as asked for | only when required |

Flow: Discovery → Activation → Execution

Two required fields keep the metadata disciplined: name is capped at 64 characters, allows lowercase letters, numbers and hyphens only, and must match the folder holding it; description runs from 1 to 1,024 characters and must say what the skill does and when to use it. The body is free-form Markdown, yet the spec advises keeping SKILL.md under 500 lines and moving long material into references/, because the agent loads the file whole at activation.

A skill folder may also carry scripts/, references/ and assets/. When instructions point at files, use paths relative to the skill root and keep them one level deep; the standard ships a skills-ref validate command to check frontmatter before a skill goes into use.

Beyond the two required fields, frontmatter accepts compatibility for environment needs such as Python or docker, license for a license name or bundled file, and metadata as a key–value map where tools store properties outside the spec.

## Spec anchor

The normative document is [agentskills.io/specification](https://agentskills.io/specification), which claims no version number, so the frontmatter records "unversioned" and pins the check date 2026-10-18 instead of guessing a revision. Anthropic developed the format and released it as an open standard, and [github.com/anthropics/skills](https://github.com/anthropics/skills) keeps the reference implementation with its spec/ and template/ folders.

## Academic anchors

No arXiv paper on the Agent Skills standard has been verified for this entry, so the academic block pins numbers measured straight from the source instead:

| Source | Figure | Measured |
| --- | --- | --- |
| [github.com/anthropics/skills](https://github.com/anthropics/skills) | approximately 181,800 stars (as of 2026-10-18), repository created 2025-09-22, ships spec/ and template/ | 2026-10-18 |
| [agentskills.io](https://agentskills.io/) | supporting clients include Claude Code, Cursor, GitHub Copilot, VS Code, ChatGPT & Codex, OpenHands, Goose, Gemini CLI | 2026-10-18 |

## FAQ

**How is SKILL.md different from an ordinary prompt?** A prompt rides along with each turn; a skill sits inside the project and the agent decides when to load it from the name and description, so the instructions survive a context reset.

**Can a skill run scripts on its own?** Yes, when the body tells it to; frontmatter can list pre-approved tools in allowed-tools, though that field is still experimental and support differs between tools.

**What does it cost in context to keep many skills?** Startup loads only about 100 tokens of metadata per skill, and the full instructions arrive at activation, so keeping dozens of skills in a project stays cheap.

**Which tools support it?** [agentskills.io](https://agentskills.io/) lists Claude Code, Claude, ChatGPT & Codex, Cursor, GitHub Copilot, VS Code, OpenHands, Goose, Amp, Gemini CLI, OpenCode, Factory and more.

**Are the example skills open source?** In the repository, many skills ship under Apache 2.0; the document skills (docx, pdf, pptx, xlsx) are source-available rather than open source, and the README notes these illustrate patterns while real behavior in Claude may differ.

A skill earns packaging only when the guidance gets reused; one-off instructions just bloat the metadata the agent reads at startup.

**Which sources built this entry?** Three pages, all fetched on 2026-10-18: [agentskills.io/specification](https://agentskills.io/specification) for the SKILL.md format, [agentskills.io](https://agentskills.io/) for the standard and its three loading stages, [github.com/anthropics/skills](https://github.com/anthropics/skills) for Anthropic's implementation.

## Related

- [AGENTS.md](/en/wiki/agents-md/)
- [What Is a Multi-Agent OS?](/en/blog/what-is-multi-agent-os/)
- [Andrew Ng's 4 AI Engineering Skills Map](/en/blog/ai-engineering-skills-map/)