Official definition: a skill is a directory containing a required SKILL.md file (YAML metadata + Markdown instructions), optionally bundling scripts, reference documents, and resources. It packages domain expertise, workflows, and best practices into reusable, version-controlled files that turn a general-purpose agent into a specialist. Anthropic's own analogy is an onboarding guide for a new hire.
Standard directory structure
- SKILL.md — required: frontmatter metadata + instruction body.
- scripts/ — optional: executable code (Python / Bash / JS, etc.).
- references/ — optional: reference docs loaded on demand.
- assets/ — optional: templates / images / data files.
Key frontmatter constraints
- name (required): max 64 chars, lowercase alphanumerics + hyphens only; no leading/trailing/consecutive hyphens; must match the directory name. Reserved words such as "anthropic" and "claude" are also disallowed. It describes what the skill does.
- description (required): max 1024 chars, should include trigger keywords that help the model tell whether a task matches.
- Optional fields: license, compatibility (environment needs), metadata (custom key-value pairs), and allowed-tools (pre-approved tools, experimental).
Timeline and adoption: Anthropic announced Agent Skills in its official blog on 2025-10-16 and published the format as an open standard on agentskills.io on 2025-12-18. Claude Code, OpenAI Codex / ChatGPT, Cursor, Gemini CLI, VS Code, Trae, and many other clients now declare the format compatible.
Scale (research): a 2026 dataset effort (arXiv: GitSkills) scraped about 3.8M SKILL.md files across 280k+ public GitHub repositories in July 2026, deduplicating to roughly 1.88M distinct contents. That shows the format has been adopted at scale — and also exposes an early-ecosystem problem: there is no central registry or package manager, so skills spread mainly by copying folders between repositories.