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 the code execution tool plus one beta header,
skills-2025-10-02; add a second,files-api-2025-04-14, only if you also use the Files API to upload/download container files. Code execution itself is now GA and needs no beta header of its own — the legacycode-execution-2025-05-22header still works as an opt-in but is no longer required (re-verified against live Anthropic docs, 2026-08-07). - 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 and the Claude API are directly corroborated via Anthropic's own docs; Google's Gemini CLI is independently confirmed via its own GitHub repo (a merged PR referencing existing
.gemini/skills/SKILL.md support). OpenAI's Codex CLI, GitHub Copilot, and Cursor each publish their own Agent Skills docs per converging search results, but those domains were blocked in this sandbox, so treat those three as corroborated-but-not-independently-fetched. Cline and Windsurf support is community-tracker-sourced only — no vendor-primary confirmation found.
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, re-verified 2026-08-07): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Claude API code execution tool docs (fetched directly, 2026-08-07 — confirms code execution is GA and requires no beta header): https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
- anthropics/skills repository README (fetched directly): https://github.com/anthropics/skills
- google-gemini/gemini-cli PR #16045, "Built-in Agent Skills" (fetched directly, 2026-08-07 — confirms pre-existing SKILL.md support, merged 2026-01-10): https://github.com/google-gemini/gemini-cli/pull/16045
- Agent Skills open standard specification (referenced by the above; not independently fetched — agentskills.io blocked in this sandbox, retried 2026-08-07): 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 blocked in this sandbox, retried 2026-08-07): 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 — developers.openai.com blocked in this sandbox, retried 2026-08-07): https://developers.openai.com/codex/skills
- GitHub Copilot — "Adding agent skills for GitHub Copilot" (existence/title corroborated via search only; docs.github.com blocked in this sandbox): https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills
- Cursor — Agent Skills docs (existence/title corroborated via search only; cursor.com blocked in this sandbox): https://cursor.com/docs/skills