Agent artifacts
Agent Skills
definition
An Agent Skill is a folder containing a SKILL.md file — YAML frontmatter plus Markdown instructions — that an AI agent discovers and loads on demand when a task matches its description.
In depth
A skill is a way to give an agent a procedure it would otherwise have to be told every time: how your team writes a migration, how to fill a particular kind of form, how to review a pull request against your standards. The folder can also carry supporting files — reference documents, templates, and executable scripts the agent may run.
The format is deliberately plain. `SKILL.md` opens with YAML frontmatter carrying at minimum a `name` and a `description`; the Markdown body holds the instructions. The description is load-bearing: it is what the agent sees when deciding whether the skill is relevant, so it needs to state both what the skill does and when to reach for it.
Skills work by progressive disclosure. Only the name and description sit in context by default. The body is read when the skill is triggered, and bundled reference files are opened only if the body points to them. That is what lets a team install many skills without drowning the context window — and it is the design difference between a skill and simply pasting more text into CLAUDE.md.
Because a skill is a directory of files rather than a code package, it travels easily: committed to a repository, shared as a plugin, or distributed to a whole organisation. Anthropic published the format openly and it is being adopted beyond Claude, which means skills are becoming a genuine artifact class with genuine distribution.
Why it matters for governance
A skill is untrusted input that behaves like trusted instruction, and it can carry scripts that execute with the engineer's own permissions. Two distinct risks follow. The Markdown can contain instructions the installing engineer never read — the file is long, the review was a glance at the description. And any bundled script is arbitrary code arriving through a channel that no software-composition-analysis tool watches, because nothing about a folder of Markdown looks like a dependency. Skills need the controls dependencies get: a known publisher, a pinned version, a diff on update, and a scan before distribution.
Frequently asked
- How is a skill different from an MCP server?
- A skill teaches the agent a procedure using capabilities it already has. An MCP server gives it a new capability — a connection to a system it otherwise could not reach. Skills are knowledge; servers are access. Many real workflows need both.
- How is a skill different from CLAUDE.md?
- CLAUDE.md is always loaded and applies to everything. A skill is loaded only when its description matches the task. Anything conditional belongs in a skill, which keeps the always-on context small.
- Can a skill run code?
- Yes. A skill folder can bundle scripts that the agent executes, subject to whatever tool permissions the host enforces. That is the strongest argument for reviewing skills before they reach a laptop rather than after.
Sources
Primary sources for the claims on this page. Specifications and vendor documentation change — verify against the source if a detail is load-bearing for a decision you are making.