An agent skill is a folder containing a file called SKILL.md, and that file tells an AI agent how to do a specific job. No installer, no registry, no API. The format was created by Anthropic in October 2025 and published as an open standard that December, and it is now read by agents from several different companies. The clever part is not the file. It is that the agent only reads it when the job comes up.
What is an agent skill?
A directory with one required file. The specification puts it plainly: "A skill is a directory containing, at minimum, a SKILL.md file." Everything else is optional, and the conventional layout is three folders beside it.
- 1SKILL.md holds the metadata and the instructions. This is the only required file.
- 2scripts/ holds executable code the agent can run. Its output enters the conversation; the script itself does not.
- 3references/ holds the detail that would bloat the main file, read only when needed.
- 4assets/ holds templates and resources the job needs.
That is the entire architecture. There is no build step and no manifest beyond the file's own header. A skill is closer to a well-written internal wiki page that happens to be executable than it is to a plugin or an app.
What is SKILL.md, and what goes in it?
A Markdown file with a YAML header on top. The header carries the metadata; everything below it is instructions, and the spec states there are "no format restrictions" on that part. The header is where portability lives, and it has exactly six fields.
| Field | Required | What it does |
|---|---|---|
| name | Yes | Max 64 characters, lowercase and hyphens, must match the folder name |
| description | Yes | Max 1024 characters. What the skill does and when to use it |
| license | No | License name, or a pointer to a bundled license file |
| compatibility | No | Max 500 characters. Environment requirements |
| metadata | No | Arbitrary key and value pairs |
| allowed-tools | No | Pre-approved tools the skill may use. Marked experimental |
Individual agents accept many more fields than these. Claude Code alone adds around fourteen, covering things like which model to use and how much effort to spend. Those extras are vendor extensions: useful, and not portable. The documentation is direct about it, saying that outside Claude Code "you can use only the fields in the spec", and a skill carrying an extra field is rejected with an error naming the six that are allowed. Writing to the six is what makes a skill work everywhere.
Do skills use up your context window?
Almost none of one, until you use them. This is the mechanism that makes the whole format work, and it is called progressive disclosure. Information loads in three stages, and only the first is paid on every conversation.
In numbers: the name and description cost roughly 100 tokens per skill and load at session start. The instructions are recommended to stay under 5,000 tokens and load only on activation. Bundled files load when referenced, and a bundled script is effectively free because it runs in the shell and only its output comes back. As the implementer guide puts it, an agent with twenty skills installed "doesn't pay the token cost of 20 full instruction sets upfront."
Progressive disclosure governs loading, not unloading. Once a skill is activated its content "stays there across later turns", so it becomes a recurring cost for the rest of that conversation. Cheap to have installed is not the same as free to use.
Skills vs MCP, agents, plugins and prompts
These four comparisons are the most searched questions in the whole topic, and the vendors have answered them directly. The distinctions below are quoted rather than reasoned out.
| Compared with | The difference, in the vendor's words | Use it when |
|---|---|---|
| A prompt | Skills are procedural knowledge that persists across conversations; a prompt is a moment-to-moment instruction in one conversation | You keep typing the same instructions again and again |
| MCP | "MCP connects Claude to data; Skills teach Claude what to do with that data" | The agent can already reach the thing, it just does the job badly |
| A subagent | A skill runs in the main conversation; a subagent works in its own context and returns a summary | You want the work visible, not delegated and summarized |
| A plugin | A plugin is the distribution wrapper. It can contain skills, agents, hooks and more | You are sharing with a team or publishing versioned releases |
| Project knowledge | "Projects say 'here's what you need to know.' Skills say 'here's how to do things.'" | The problem is method, not missing background |
The cleanest single test comes from the same vendor guidance: "If you find yourself typing the same prompt repeatedly across multiple conversations, it's time to create a Skill." Everything else follows from that.
How do you install an agent skill?
You put the folder in the right place. That is the entire process for most tools, and it is why the format spread quickly. In Claude Code the locations are documented as a short table: ~/.claude/skills/ for every project you work on, .claude/skills/ inside a single project, plus plugin and enterprise-managed locations.
In practice the friction is lower than that sounds. Modern agents will do the filing themselves: unzip the folder anywhere, point the agent at it, and ask it to install the skills. Distribution through a marketplace is the other route, using commands such as /plugin marketplace add owner/repo followed by /plugin install name@marketplace.
The specification standardises the file, not where it lives. As the implementer guide says, it "does not mandate where skill directories live (it only defines what goes inside them)". A convention has emerged around .agents/skills/ for cross-tool sharing, and many tools also read .claude/skills/ for compatibility. If a skill is not being picked up, the path is usually the reason.
Which AI tools support agent skills?
Rather more than most people realise, and the list is no longer one company's. Checking each vendor's own documentation confirms SKILL.md support in Claude Code, the Claude apps and API, the Claude Agent SDK, Cowork, OpenAI's ChatGPT and Codex, GitHub Copilot, VS Code, Cursor, goose and Kimi CLI, among others.
The standard itself is Apache 2.0 for code and CC BY 4.0 for the documentation, and the repository states that the format "was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." One honest caveat: unlike the Model Context Protocol, which went to the Linux Foundation's Agentic AI Foundation in December 2025, Agent Skills has no neutral governance body and no published version number. It is open in license and in contribution, without a formal steward.
Are agent skills safe to install?
Treat them as software from a stranger, because that is what they are. The vendor warning is unusually blunt: use skills only from trusted sources, because "a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose."
The research bears that out. An academic study published in January 2026 collected 42,447 published skills and analysed 31,132 of them, finding that 26.1% contained at least one vulnerability across prompt injection, data exfiltration, privilege escalation and supply chain risks. Skills bundling executable scripts were 2.12 times more likely to be affected than instruction-only ones. A separate vendor scan of 3,984 skills in February 2026 found 13.4% carried a critical-level issue and confirmed 76 malicious payloads by human review.
The framing that matters: agent skills are a software supply chain, and they deserve the same scrutiny as any package registry. A demonstration in December 2025 showed a legitimate published skill modified to fetch and run ransomware under the same single approval the original asked for.
There is one specific trap worth naming. The allowed-tools field is honoured even in a folder you have never marked as trusted, which means "a skill can grant itself broad tool access". Reading that field before running an agent in a repository you did not write is a thirty-second habit worth forming.
When does a skill add nothing?
Often, and the format's own authors say so. The official best-practice guidance asks writers to test each instruction against one question: "Would the agent get this wrong without this instruction?" If the answer is no, cut it. And plainly: "if the agent already handles the entire task well without the skill, the skill may not be adding value."
Two more failure modes are documented rather than theoretical. Overly comprehensive skills "can hurt more than they help", because the agent struggles to find what matters and may follow instructions that do not apply. And a skill generated by asking a model to write one, with no domain knowledge supplied, produces exactly the vague filler you would expect: handle errors appropriately, follow best practices.
Activation is also probabilistic rather than guaranteed. A skill is advice the agent may take, not a rule it must follow, which is a meaningful difference if you are relying on one for something that must happen every time.
What do people actually build with agent skills?
The interesting uses are not single tricks but pipelines: a sequence of skills that hand work to each other, each owning one stage. Producing a narrated video is a good example, because it needs research, writing, audio, animation and packaging, and each of those is a different discipline with its own rules.
- →Making video with an agent. The three routes an agent can take to a finished video, what each costs, and the licensing threshold that surprises small companies: how to make videos with Claude Code.
- →Choosing a voice you can legally sell. Most free AI voices cannot be used commercially, and the popular ones are usually the ones that cannot: which free AI voice overs you can actually sell.
- →Running it on the machine you own. Two different jobs share the name local AI video, and only one of them needs an expensive graphics card: what your PC can actually run.
- →Publishing without losing the money. The platform rules quoted at source, including the one that actually catches narrated channels: AI voice and YouTube monetization.
Best Answer Hub AI Agent Skills
Ready-made skill packs for AI coding agents, bought once. The first is a five-skill pipeline that carries a topic from research through script, narration and animation to a finished video, running on your own machine.
See the skill packsFrequently asked questions
~/.claude/skills/ for all projects, or .claude/skills/ for one project. Easier in practice is to unzip it anywhere and ask the agent to install the skills from that folder. Marketplaces install through a plugin command instead..agents/skills/ for cross-tool sharing, and many agents also read .claude/skills/. When a skill is not detected, the wrong directory is the usual explanation.Sources
- Agent Skills specification: the directory structure, the six frontmatter fields and their constraints, and the three levels of progressive disclosure with token guidance.
- Agent Skills client implementation guide: the per-tier token costs, and the note that the specification does not mandate where skill directories live.
- Agent Skills best practices: the 500-line ceiling, the warning about overly comprehensive skills, and the statement that a skill may add no value.
- The Agent Skills repository: Apache 2.0 for code, CC BY 4.0 for documentation, and the origin statement.
- Claude Code skills documentation: the install paths, the portable-versus-vendor field split, the persistence caveat, and the allowed-tools warning.
- Skills explained (5 March 2026): the quoted comparisons against prompts, projects, MCP and subagents.
- Agent Skills overview: the progressive disclosure architecture and the trusted-sources security warning.
- Anthropic engineering, Agent Skills (16 October 2025, updated 18 December 2025): the open-standard publication.
- Agent Skills in the Wild (arXiv, January 2026): 42,447 skills collected, 31,132 analysed, 26.1% with at least one vulnerability, and the 2.12x figure for skills bundling scripts.
- ToxicSkills (February 2026): 3,984 skills scanned, 13.4% with a critical issue, 76 malicious payloads confirmed by human review.
- Weaponizing skills (December 2025): the proof-of-concept modifying a published skill to run ransomware under the same approval.
- VS Code agent skills, Cursor, GitHub Copilot and OpenAI: independent vendor confirmation of SKILL.md support.
- Linux Foundation Agentic AI Foundation (December 2025): the founding contributions, which include MCP and not Agent Skills.
- The reference skills repository: star count as read in August 2026.
Read next from Best Answer Hub: making videos with Claude Code, free AI voice overs you can sell, local AI video without a graphics card, and AI voice and YouTube monetization. The packs live at AI Agent Skills.