What are AI agent skills?
An AI agent skill is a packaged, reusable procedure that an agent loads only when a task calls for it, instead of carrying every possible instruction in context at all times. In practice a skill is a folder: one file that describes what the skill does and when to use it, plus any scripts, templates, or reference documents the procedure needs. The agent's runtime keeps a short list of available skills in view, and loads a skill's full content only when it decides the task matches.
The pattern was popularized by Anthropic's Agent Skills, announced on October 16, 2025 as a way to package instructions, scripts, and resources that Claude can load on demand across Claude.ai, Claude Code, and the API. A December 18, 2025 update turned it into an open, cross-vendor standard. GitHub Copilot in VS Code, the Copilot CLI, and other agent runtimes can now load the same SKILL.md-based folders, with the shared specification published at agentskills.io.
In plain words
Think of a skill as a laminated card a specialist keeps in a drawer rather than in their head. A support engineer does not memorize every runbook; they know which drawer to open when a specific kind of incident shows up, and they only read that one card. An AI agent skill works the same way: the agent keeps a one-line index of what each card covers, and only pulls a card out of the drawer when the current task actually needs it.
How a skill is structured
A minimal skill is a directory with a SKILL.md file at its root:
- A short description, always visible. Every skill contributes one or two sentences (name plus description) to the agent's context, so it always knows a skill exists and roughly what it is for. This costs very little context even with dozens of skills installed.
- Instructions, loaded on invocation. The body of
SKILL.md, the actual step-by-step procedure, only enters context once the agent decides to use that skill for the current task. - Supporting files, loaded on demand. Reference documents, examples, and scripts sit next to
SKILL.mdand are read only if the instructions point the agent to them. A skill can ship large reference files and cost close to nothing until a step actually needs them.
This three-tier loading is usually called progressive disclosure: cheap metadata everywhere, the real instructions on demand, and heavy reference material only when a specific step calls for it. It is what makes it practical to give an agent access to dozens of narrow, specific procedures instead of one long, generic system prompt that tries to cover every case at once.
Why they matter
- Context stays small as capability grows. Adding a new skill costs roughly the size of its description, not its full content. An agent can carry a large library of procedures without every one of them eating into the context budget on every turn.
- Skills are portable. The format is now shared across multiple agent runtimes. A deployment checklist or a house coding standard written once works wherever an agent that understands
SKILL.mdruns, instead of being locked into one product's prompt format. - They separate "what to do" from "when to do it." The description decides when a skill fires; the body decides what happens once it does. That split makes each piece easier to change and test independently.
- They encode the procedure and the tools it needs. A skill can bundle an actual script, a validation checklist, or a template alongside the instructions, so the agent follows a tested procedure instead of reconstructing one from a general-purpose prompt every time.
The agent systems we build and run for ourselves at DX Heroes package recurring procedures as versioned skill files rather than one long prompt. Board hygiene, review checklists and a writing-style check each live in their own file, and that is what lets our agents run these processes unattended instead of needing the steps re-explained every time.
What to watch out for
- A skill description that is too vague does not fire when it should, or fires when it should not. The one or two sentences an agent sees before deciding to load a skill carry all the weight; a generic description undermines the whole mechanism.
- A skill is not a permission boundary. The optional
allowed-toolsfield only adds access and never removes it. It lists tools the agent may use without asking for approval, and Claude Code applies it for the turn that invokes the skill. Deny rules still override it, every unlisted tool stays callable, and a skill checked into a repository can grant itself broad access. Read theallowed-toolsline of a skill the way you would read any other change to permissions, and keep the real limits in the runtime. - Too many overlapping skills confuse selection. If three skills plausibly match the same task, the agent has to guess which one to load. Keep descriptions specific enough that they do not collide.
- A skill is not a place for secrets. Instructions and scripts inside a skill folder are typically committed to a repository or shared across a team; credentials and tokens belong in environment configuration, not in a
SKILL.mdfile or its supporting scripts. - Stale skills quietly rot. A procedure that changes on the ground but not in its skill file leaves the agent confidently following outdated steps. Skills need the same maintenance discipline as any other piece of documentation.
Related articles:
- What's an agent? – The base concept a skill extends: an AI that handles a task on its own once you give it the goal.
- What is agentic AI? – Why an agent that plans and acts across steps needs procedures it can load selectively, not one long prompt.
- AI agent orchestration – How multiple agents, each potentially drawing on different skills, coordinate on a larger task.
- Context engineering: the new developer skill – The wider discipline of deciding what an AI tool sees; progressive disclosure in skills is one concrete technique for doing it.
- What is MCP elicitation? – Another on-demand mechanism in the same family: instead of loading a procedure, the agent asks the user a structured question mid-task.
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.