What are Agent Skills (SKILL.md)?
Agent Skills are an open format in which a folder holding a SKILL.md file, plus optional scripts, references and assets, teaches an AI agent a specific task and loads into context only when that task comes up.
Checked
A skill is the unit of reusable know-how for an agent: how to fill a particular form, run a release, review a contract against a house checklist, or build a slide deck in a company template. Instead of putting every procedure in one long system prompt, each lives in its own folder and the agent reads it only when a task matches.
Anthropic introduced Skills on 16 October 2025, published the format as an open standard on 18 December 2025, and donated it to the Linux Foundation's Agentic AI Foundation on 22 October 2026. OpenAI's Codex and ChatGPT, Microsoft Agent Framework, LangChain's Deep Agents and the Claude Agent SDK all load skills in the same format.
How it works
Agents load skills by progressive disclosure, in three stages. At discovery, only each skill's name and description sit in context, about 100 tokens per skill. At activation, when a task matches the description, the agent reads the full SKILL.md body; the spec recommends under 5,000 tokens and under 500 lines. At execution, the agent follows the instructions and opens bundled scripts, references or assets only as needed.
Required frontmatter
name: 1 to 64 lowercase letters, digits and single hyphens, matching the folder name. description: 1 to 1,024 characters saying what the skill does and when to use it.
Optional frontmatter
license, compatibility (up to 500 characters on environment needs), a free-form metadata map, and allowed-tools, which is experimental and varies by agent.
Optional folders
scripts/ for code the agent can run, references/ for documentation it reads on demand, and assets/ for templates, images and data files.
Validation
The skills-ref reference library checks frontmatter and naming with skills-ref validate.
Status and adoption, checked 1 November 2026
Governance
An Agentic AI Foundation project since 22 October 2026, alongside MCP, AGENTS.md and A2A. The spec repo, agentskills/agentskills, is Apache-2.0 with 26,839 GitHub stars; Anthropic's example repo, anthropics/skills, has 186,034.
OpenAI Codex and ChatGPT
Skills build on the agentskills.io standard. Codex loads them from .agents/skills folders in the repo and home directory, from /etc/codex/skills and from bundled system skills, and invokes them explicitly by name or implicitly when a task matches the description.
Claude Agent SDK and Claude Code
Skills load from the project's .claude/ folder and the user's ~/.claude/.
Microsoft Agent Framework
Skills, as reusable packages of instructions, scripts and resources, were in preview at the 1.0 release in April 2026.
When to use a skill, and when not to
Use a skill for
A procedure the agent needs sometimes, not always: a report format, a deployment checklist, a domain rulebook, or a script that does a step deterministically.
Use MCP instead for
Access to a live system such as a CRM, database or ticketing tool. MCP supplies connectivity; skills supply expertise, and many skills tell the agent how to use an MCP server well.
Use AGENTS.md or the system prompt for
Rules that apply to every task, such as tone, safety limits or repository conventions. Those should not depend on a description match to load.
One agent, many skills
Anthropic's January 2026 guidance is to build one general agent and specialise it with a skills library, rather than a separate agent for each domain.
Gotchas from production
The description is the router
A vague description means the skill never loads, or loads for the wrong task. OpenAI's guidance is to write descriptions as routing logic and include cases where the skill should not trigger, then test that it fires only when it should.
Skills are code
Scripts run with the agent's permissions. A third-party skill deserves the review a new dependency gets, and a sandbox limits the damage if it misbehaves.
allowed-tools is not portable
The field is experimental and support varies between agents, so pre-approved tools in one product may still prompt, or be ignored, in another.
Keep references shallow
The spec advises file references one level deep from SKILL.md. Deep chains of files cost context and are easy for the agent to miss.
Skills age with the model
As models get stronger, rigid step-by-step recipes can turn into scaffolding the model no longer needs, so a skill library needs the same eval-driven review as prompts.
Agent Skills compared with MCP and always-on instructions
| Agent Skills | MCP server | AGENTS.md or system prompt | |
|---|---|---|---|
| What it carries | Instructions, scripts and resources for a task | Tools and data from a live system | Rules for every task |
| When it enters context | Name and description always; body on match | Tool definitions when the server connects, unless tool search defers them | Always |
| Format | Folder with SKILL.md (YAML frontmatter plus Markdown) | Protocol over stdio or HTTP | Markdown file or prompt text |
| Where code runs | In the agent's own sandbox | In the MCP server process | No code |
| Governance | Agentic AI Foundation (since 22 Oct 2026) | Agentic AI Foundation (founding project, Dec 2025) | AGENTS.md: Agentic AI Foundation |
| Typical failure | Never triggers, or triggers on the wrong task | Too many tools crowd the context | Grows until rules contradict each other |
Common questions
What is the difference between Agent Skills and MCP?
MCP connects an agent to tools and data in other systems. A skill teaches the agent how to do a task, with instructions and scripts loaded only when needed. They are complementary, and a skill often explains how to use an MCP server well.
Who created Agent Skills?
Anthropic introduced Skills in October 2025, opened the format as a standard in December 2025, and donated it to the Linux Foundation's Agentic AI Foundation on 22 October 2026.
Do Agent Skills work with OpenAI Codex?
Yes. OpenAI's docs state that skills for ChatGPT and Codex build on the open agentskills.io standard, with skills stored in .agents/skills folders.
How long should a SKILL.md file be?
The specification recommends keeping the body under 500 lines and under about 5,000 tokens, and moving detailed material into separate reference files the agent reads on demand.
Related
Skills vs MCP
Connectivity to systems, compared with packaged expertise the agent loads on demand.
Progressive disclosure
Show the menu first, load the dish only when it is ordered.
Model Context Protocol (MCP)
The open standard for plugging tools and data into AI agents.
AGENTS.md
A README for coding agents: the file an agent reads first in a repo.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Sources
- agentskills.io, Agent Skills overview
- agentskills.io, Specification (frontmatter limits, progressive disclosure)
- Anthropic, Equipping agents for the real world with Agent Skills (2025-10-16)
- Claude blog, Skills (2025-10-16, open-standard update 2025-12-18)
- Linux Foundation, AAIF adds Agent Skills and three other projects (2026-10-22)
- GitHub, agentskills/agentskills (26,839 stars, 1 Nov 2026)
- OpenAI, Build skills for ChatGPT and Codex
- Claude blog, Building agents with skills (2026-01-22)
- OpenAI, Shell + Skills + Compaction: tips for long-running agents
- Microsoft, Microsoft Agent Framework Version 1.0 (2026-04-03)
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.