Agent Skills — Specification (agentskills.io)
by Agent Skills (open standard)
The formal, vendor-neutral spec for the SKILL.md format now implemented across dozens of agents.
Overview
The Specification page at agentskills.io is the formal, vendor-neutral format spec for Agent Skills — the SKILL.md standard Anthropic originally developed and then released openly, now implemented by Claude Code, Cursor, VS Code, GitHub Copilot, Gemini CLI, OpenAI Codex, OpenHands, Goose, Roo Code and dozens of other agent clients. It defines the directory layout: a skill is a folder containing at minimum a SKILL.md, with optional scripts/, references/ and assets/ subfolders whose conventions the page spells out. It then gives the complete YAML frontmatter schema. Required fields are name — 1 to 64 characters, lowercase alphanumerics and hyphens only, no leading, trailing or consecutive hyphens, and it must match the parent directory name — and description, 1 to 1024 characters, describing both what the skill does and when to use it with keywords that help an agent match a task. Optional fields are license, compatibility (max 500 characters, for environment requirements), metadata (a string-to-string map for client-specific properties) and the experimental allowed-tools, a space-separated list of pre-approved tools. The page formalizes three-tier progressive disclosure: roughly 100 tokens of metadata loaded at startup for every skill, the SKILL.md body loaded on activation with an under-5000-token recommendation and a 500-line ceiling, and bundled resources loaded only on demand. It closes with file-reference rules — relative paths, one level deep — and validation through the skills-ref reference library. The standard is developed at github.com/agentskills/agentskills; code is Apache-2.0 and documentation CC-BY-4.0.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~10 min read
- Provider
- Agent Skills (open standard)
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓The complete Agent Skills directory structure and which files are actually required
- ✓Every frontmatter field including optional license, compatibility, metadata and allowed-tools
- ✓The exact naming rules a valid skill name must satisfy, with invalid examples given
- ✓How to write a description an agent can reliably match against an incoming task
- ✓How three-tier progressive disclosure bounds the context cost of keeping many skills loaded
- ✓The file-reference conventions that keep bundled scripts and references loadable on demand
- ✓How to validate a skill locally with the skills-ref reference implementation before shipping
Highlights
- •The authoritative vendor-neutral standard rather than one product's own documentation
- •Documents optional fields — compatibility, metadata, allowed-tools — that product docs often omit
- •Gives concrete valid and invalid name examples instead of leaving the rules as prose
- •Points at official validation tooling, so conformance is checkable rather than guessed at
- •Backed by a 24k-star open repository with Apache-2.0 code and CC-BY-4.0 documentation
Who It’s For
Best For
- ✓Tool builders implementing Agent Skills support inside their own agent runtime
- ✓Authors writing portable skills that must work identically across multiple clients
- ✓Teams standardizing an internal skill library and needing a conformance target
Prerequisites
- •Familiarity with YAML frontmatter and Markdown
- •A basic understanding of what an agent skill is and the problem it solves
FAQ
What is Agent Skills — Specification (agentskills.io)?
The complete open-standard format specification for Agent Skills: directory layout, the full YAML frontmatter schema with exact character and naming constraints, the three-tier progressive disclosure model, file-reference rules and official validation tooling. Afterwards you can author skills that load correctly in any compliant client, or implement skill support in your own agent runtime against a conformance target.
Is Agent Skills — Specification (agentskills.io) free?
Agent Skills — Specification (agentskills.io) is free to access.
What level is Agent Skills — Specification (agentskills.io) for?
Agent Skills — Specification (agentskills.io) is aimed at a intermediate audience. Recommended background: Familiarity with YAML frontmatter and Markdown, A basic understanding of what an agent skill is and the problem it solves.
How long does Agent Skills — Specification (agentskills.io) take?
Expect roughly ~10 min read. Most learners work through it at their own pace.
What will I learn from Agent Skills — Specification (agentskills.io)?
You'll learn: The complete Agent Skills directory structure and which files are actually required; Every frontmatter field including optional license, compatibility, metadata and allowed-tools; The exact naming rules a valid skill name must satisfy, with invalid examples given; How to write a description an agent can reliably match against an incoming task; How three-tier progressive disclosure bounds the context cost of keeping many skills loaded; The file-reference conventions that keep bundled scripts and references loadable on demand; How to validate a skill locally with the skills-ref reference implementation before shipping.
Topics
Sources
This page was written from 3 sources, 2 on domains other than agentskills.io.