Agent Skills Explained: The SKILL.md Open Standard
What Agent Skills are, the exact SKILL.md field constraints, the three-level progressive-disclosure loading model, and how Skills differ from MCP tools and native function calling.
Agent Skills is an open, filesystem-based format for packaging procedural knowledge — reusable instructions, scripts, and reference material — that agentic coding tools load into an LLM's context only when needed. Anthropic introduced it in December 2025 as a specification independent of Claude's own implementation, published separately at agentskills.io.
Key facts
- A Skill is a directory containing a required
SKILL.mdfile plus optional bundled files (scripts/, reference docs, templates). SKILL.mdneeds only two YAML frontmatter fields:name(max 64 chars, lowercase letters/numbers/hyphens only, no XML tags, cannot contain "anthropic" or "claude") anddescription(non-empty, max 1024 chars, no XML tags, must state both what the skill does and when to use it).- Skills load in three stages ("progressive disclosure"): Level 1 metadata (name + description, ~100 tokens, always in the system prompt); Level 2 the SKILL.md body (read only when triggered, recommended under 5,000 tokens); Level 3 bundled scripts/resources (read or executed only as referenced — effectively unlimited).
- Bundled scripts run via bash/code execution and return only their output to context — the script source itself never consumes tokens.
- On the Claude API, Skills require three beta headers:
code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14. - Example Skills are Apache-2.0 licensed; Anthropic's own pre-built document Skills (docx/pdf/pptx/xlsx) are source-available, not open source.
- Multiple independent tools now read the same format: Claude Code, the Claude API, and OpenAI's Codex CLI (which publishes its own Agent Skills docs) are directly corroborated; community trackers additionally list Google's Gemini CLI and further integrations (GitHub Copilot, Cursor, Cline, Windsurf) — exact adoption counts vary by source and were not all independently verified here.
How Skills differ from MCP and function calling
Skills are not a network protocol — there is no JSON-RPC handshake or tools/list call. A host discovers Skills by loading directory metadata into the system prompt at startup, then reads the full file from the filesystem via bash only when relevant. See /resources/mcp-vs-function-calling for how MCP and native function/tool calling differ from each other. The three layers compose: a Skill's instructions can tell an agent to call an MCP tool or invoke a function — Skills package how to do a task, MCP and function calling provide what the agent can call.
Where Skills run
- Claude API — no network access inside the execution container, only pre-installed packages; reference pre-built Skills by
skill_id(pptx, xlsx, docx, pdf) or upload custom ones via/v1/skills(workspace-shared). - Claude Code — filesystem-based, no upload step; personal (
~/.claude/skills/) or project-scoped (.claude/skills/); full local network access. - claude.ai — custom Skills are per-user (not org-wide), uploaded as a zip via Settings; network access depends on admin configuration.
Security note
A Skill runs with whatever tool/file/network access the host already grants the agent — a malicious or compromised Skill (especially one bundling code that fetches external content) can exfiltrate data or misuse tools exactly like a hostile MCP server or a poisoned prompt. Audit every bundled file before installing a Skill from an untrusted source. See /resources/agentic-security-checklist for the general threat model and /resources/agent-memory-context for how "procedural memory" as a concept relates to this concrete format.
Verified sources
- Agent Skills overview (Claude Platform docs, fetched directly): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- anthropics/skills repository README (fetched directly): https://github.com/anthropics/skills
- Agent Skills open standard specification (referenced by the above; not independently fetched — 403 in this sandbox): https://agentskills.io/specification
- Anthropic engineering blog, "Equipping agents for the real world with Agent Skills" (cited by the docs above; not independently fetched — anthropic.com is sandbox-blocked): https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- OpenAI Codex — Agent Skills docs (existence and title corroborated via search index; not independently fetched — 403 in this sandbox): https://developers.openai.com/codex/skills