# What Is an AI Agent Skill? > A skill is a folder of instructions your AI agent loads on demand — a SKILL.md plus any scripts it needs. What goes in the folder, how the agent decides to load it, and why that beats pasting the same prompt every session. By Michał Jaskólski · Published 2026-08-17 · Updated 2026-08-17 · 10 min read Canonical: https://skills.wondel.ai/learn/what-is-an-ai-agent-skill/ Skills used: clean-code, lean-startup, domain-driven-design, cro-methodology **TL;DR:** An AI agent skill is a folder containing a SKILL.md file — YAML metadata plus written instructions — that an agent loads only when a task matches the skill's description. The folder can bundle scripts, reference documents and templates. Skills follow an open standard, so the same folder works across Claude Code, Codex, Cursor and dozens of other agents. - A skill is a folder, not a plugin: a required SKILL.md, plus optional scripts, references and assets. - The description field is the trigger — it is the only part of most skills an agent reads before deciding whether the rest is relevant. - Progressive disclosure is the whole point: many skills can sit on disk while costing almost nothing in context until one is needed. - Skills are an open format, so a skill you write once is portable across agents rather than locked to a single vendor. - Skills complement MCP and subagents rather than replacing them — MCP adds capabilities, a skill adds judgment about how to use them. Every team that starts using coding agents seriously hits the same wall within about a month. You work out the right way to ask for something — the exact framing that gets a pull request reviewed properly, or an MVP scoped the way you actually scope MVPs — and then you paste it. Again. Into tomorrow's session, into a teammate's session, into a different agent on a different machine. The knowledge is real and hard-won. The delivery mechanism is a text file you keep reopening. An AI agent skill is the fix for that. It is a folder of instructions — a `SKILL.md` file plus whatever scripts, reference documents and templates it needs — that your agent loads on demand, at the moment a task calls for it. You write it once. It lives on disk, or in a git repo, or in a shared team directory. The agent decides when it is relevant and pulls it into context by itself. That is the entire idea, and its unglamorousness is the feature. No runtime, no API, no server to keep alive — a directory with a markdown file in it. Which is precisely why the format spread across two dozen agent products in months. ## What is an agent skill, precisely? The [Agent Skills](https://agentskills.io) standard defines it plainly: a skill is a directory containing, at minimum, a `SKILL.md` file. That file holds YAML frontmatter with metadata — a `name` and a `description` are required — followed by markdown instructions telling the agent how to do something. ``` clean-code/ ├── SKILL.md # required: metadata + instructions ├── scripts/ # optional: executable code ├── references/ # optional: deeper documentation └── assets/ # optional: templates, data files ``` The instructions are written for a machine that reads English, so they look like a well-organised internal wiki page rather than code: principles, procedures, tables of before-and-after examples, edge cases, a diagnostic checklist. The important word here is *folder*. Not a prompt, not a config setting, not a service. Something you can read, diff, review in a pull request, and copy to another machine with `cp -r`. Every property that makes skills useful in a team follows from that. ## What's actually inside the folder? Four things, only the first of which is mandatory. **`SKILL.md`** is the required file, and the only one many skills have. Its frontmatter carries the metadata; its body carries the instructions. The standard caps `name` at 64 characters (lowercase, hyphenated, matching the parent directory) and `description` at 1024, and recommends keeping the body under 500 lines. We cover the anatomy field by field in [SKILL.md, explained](https://skills.wondel.ai/learn/skill-md-explained/). **`scripts/`** holds executable code the agent runs rather than reimprovises — a Python file that converts a document, a shell script that queries a deployment. Deterministic work belongs here; the agent should decide *when* to run it, not regenerate it each time. **`references/`** holds material that would bloat `SKILL.md` if inlined: API references, per-language conventions, worked examples. The agent reads these only when a task needs them, so keeping each one focused is the trick. **`assets/`** holds static resources: document templates, configuration boilerplate, lookup tables, diagrams. Beyond that, the standard permits any files you like. The three folder names are conventions rather than requirements — useful because agents and humans both benefit from a predictable layout. ## How does an agent decide to load a skill? This is where skills earn their keep, and it is the part most explanations skip. The mechanism is **progressive disclosure**, and the standard describes it in three stages. Discovery: the agent loads only the `name` and `description` of each available skill — roughly a hundred tokens each — so it knows what exists and when each might matter. Activation: when a task matches a description, the agent reads that skill's full `SKILL.md` into context. Execution: it follows the instructions, loading referenced files or running bundled scripts only if the work requires them. So you can have fifty skills installed and pay almost nothing for the forty-nine irrelevant to what you are doing right now. A library that would be unusable if pasted wholesale becomes practical because the agent only ever reads the slice it needs. > Fifty skills on disk cost about as much context as one paragraph — until one of them is the right skill, and then you get all of it. It also explains why the `description` field carries disproportionate weight. That single line is, for most of a session, the *only* thing the agent knows about your skill. "Helps with code quality" will never trigger, because nobody's request looks like that. Name the situations — "use when the user mentions code smells, this function is too long, or reviewing a pull request for readability" — and it fires when it should. One honest caveat: exactly *when* an agent reads those descriptions, how it matches them, and whether you can force a load are implementation details that differ between products. The standard describes discovery as happening at startup, and that is the model to design against — but some agents re-scan, and some expose skills as a tool the model calls explicitly. If a skill you expected to fire stays quiet, naming it directly is the reliable fallback. Anthropic's [Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) covers the Claude side; the [specification](https://agentskills.io/specification) covers what conforming agents agree on. ## Why not just paste the instructions into the prompt? You can. For a one-off, you should. The case for a skill is what happens on the second, twentieth and two-hundredth use. **Context economy.** A pasted instruction block occupies context from the moment you send it until the conversation ends, whether or not the task needs it. A skill occupies roughly one line until it is relevant. Multiply that across a dozen practices and pasting stops being viable. **Reuse without decay.** Prompts kept in a scratch file get edited, half-remembered, and re-derived. A skill is a single artifact with one canonical version. When you learn a step was missing, you fix it in the file, and every future session — yours and everyone else's — gets the fix. **Consistency across sessions and people.** This is the quiet one. If the way your agent reviews code depends on which teammate is prompting it, you do not have a code review standard; you have a distribution of moods. A shared skill makes the *method* the artifact instead of the phrasing, and new joiners inherit the team's accumulated judgment on day one. **It is code, so treat it like code.** A skill lives in git — review a change to it, blame a line, roll it back, tag a version. And because reference files load on demand, it can carry far more depth than you would type into a chat box. > **Prompt** — Use the `clean-code` skill to review the pull request on my current branch — flag any function doing more than one thing, every name that does not reveal intent, and any swallowed exceptions, then give me the top five fixes in priority order > (https://skills.wondel.ai/skills/clean-code/) ## Does a skill work in more than one agent? Yes, and this is the part that changed the calculus for most teams. The format was originally developed by [Anthropic](https://www.anthropic.com/) and released as an open standard, now maintained in the open at [agentskills.io](https://agentskills.io). Adoption has been broad and fast: Claude and [Claude Code](https://code.claude.com/docs/en/skills), OpenAI's Codex, Cursor, GitHub Copilot and VS Code, Gemini CLI, OpenCode, Goose, Amp, OpenClaw and a long tail of others all read the same `SKILL.md` layout. So the folder you write is not a bet on a vendor — move to a different agent and your skills come with you unchanged. Support is not perfectly uniform, though. Every conforming agent handles the required core — the directory layout, `name`, `description`, the markdown body — while optional fields such as `allowed-tools` are explicitly marked experimental and installation paths differ between products. If portability matters, stay on the core. We go deeper in [the agent skills standard, explained](https://skills.wondel.ai/learn/agent-skills-standard/), and on per-agent mechanics in [how to install skills](https://skills.wondel.ai/learn/how-to-install-claude-code-skills/). ## How do skills relate to MCP, subagents and slash commands? They are not competitors. They solve different halves of the same problem, and picking the wrong one wastes real time. **MCP** — the Model Context Protocol — gives an agent *capabilities*: a live connection to your database, your issue tracker, your monitoring stack. A skill gives an agent *judgment*: what to do, in what order, and what "good" looks like. They compose — MCP hands the agent the ability to query production, a skill tells it how to investigate an incident with that access. Need fresh data or a side effect in an external system? MCP. Need a method applied consistently? A skill. The full comparison lives in [Claude skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/). **Subagents** are about *isolation and parallelism* — spawning a separate context to do a chunk of work and report back, so a long investigation does not flood your main conversation. A subagent is a worker; a skill is the instruction sheet that worker reads. They stack. See [skills vs subagents vs prompts](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/) for how to choose. **Slash commands** are *explicit invocation* — you type the name, the thing runs, every time. Skills are implicit: the agent decides. Use a command when you never want the behaviour firing on its own, a skill when you want the agent to notice the situation for you. In several agents you can have both, with a command that simply forces the skill to load. ## When is a skill the wrong tool? Skills are not a universal wrapper, and treating them as one produces a library nobody trusts. Skip the skill when the instruction is **genuinely one-off**. The cost of a skill is not writing it — it is maintaining it, and every skill you keep is a description competing for the agent's attention. Skip it when what you need is **data, not method**. "What are our current error rates?" is a query, and it wants MCP or a script. Skills carry procedural knowledge, not facts that go stale. Skip it when the behaviour should be **unconditional**. If something must apply to every interaction — a house style rule, a hard security constraint — put it in your agent's always-loaded instructions file (`CLAUDE.md`, `AGENTS.md`, or the equivalent). Skills are conditional by design; that is the wrong property for a rule with no exceptions. Skip it when the work is **deterministic**. If the steps never vary and the output is mechanical, write the script and call it — though a skill that says *when* to run it may still earn its place. And be suspicious of the **skill that is really a summary**. The most common failure we see is a `SKILL.md` that describes a topic rather than directing an agent through it — an encyclopedia entry that changes nothing about the agent's behaviour. If your instructions would work equally well as a blog post, they are not yet a skill. [How to write an agent skill](https://skills.wondel.ai/learn/how-to-write-an-agent-skill/) goes through the rewrite. > A skill is not what your agent knows. It is what your agent does, and when it decides to do it. ## What does this look like in practice? Each of our 50 skills packages a canonical framework — [Lean Startup](https://skills.wondel.ai/skills/lean-startup/) for validating an idea, [Domain-Driven Design](https://skills.wondel.ai/skills/domain-driven-design/) for modelling a business, [Clean Code](https://skills.wondel.ai/skills/clean-code/) for readable functions, [CRO Methodology](https://skills.wondel.ai/skills/cro-methodology/) for a landing page that will not convert — so the agent applies the real method rather than a generic-sounding version of it. That is the practical value of the format. You are rarely short of an opinion about how work should be done. You are short of a way to make the agent hold it consistently, for everyone on the team, without you in the room. > **Prompt** — Use the `lean-startup` skill to map the leap-of-faith assumptions behind the feature I just described, rank them by which failure would be fatal, and design the smallest experiment that tests the riskiest one > (https://skills.wondel.ai/skills/lean-startup/) ## Frequently asked questions ### Is an AI agent skill the same as a prompt? No, though a skill contains prompt-like instructions. A prompt is something you send once, in one session, occupying context from the moment you send it. A skill is a file on disk that an agent loads only when a task matches its description, and that the same agent — or a teammate's — can load again tomorrow without you retyping anything. The difference that matters is conditionality and reuse: a prompt is a message, a skill is an artifact you can version, review, and share. ### Do I need to install anything to use skills? You need an agent that supports the format, which most now do. Beyond that, a skill is just a folder placed where your agent looks for skills, so installing one can be as simple as copying a directory. Package managers make it easier — our library installs with a single npx command. Per-agent details differ enough that we split them into a dedicated installation guide. ### How many skills is too many? There is no hard ceiling, because progressive disclosure means unused skills cost roughly a line of context each rather than their full contents. The real constraint is description quality, not count. Fifty skills with sharp, situation-naming descriptions work fine; ten with vague overlapping ones produce an agent that loads the wrong skill. If skills are misfiring, tighten descriptions rather than deleting them. ### Can a skill run code, or is it just text? Both. The markdown instructions are the core, but a skill folder can bundle executable scripts the agent runs directly, plus reference documents and templates it reads on demand. That is the recommended pattern for anything deterministic: put the mechanical step in a script so the agent executes it rather than regenerating it, and reserve the markdown for the judgment about when to run it. ### Who writes agent skills — vendors or users? Anyone. The format is open and the barrier is a text file, so skills come from vendors shipping them alongside products, open-source libraries like ours, and — most commonly — teams writing their own. The highest-value skills are usually internal ones: your deployment procedure, your review standards, the three gotchas in your legacy billing module. Nobody else can write those. ### Do skills work with agents other than Claude? Yes. The format was created by Anthropic but released as an open standard, and adopted well beyond Claude — Codex, Cursor, Copilot and VS Code, Gemini CLI, OpenCode, Amp, Goose, OpenClaw and others read the same layout. Stick to the required core of the specification and a skill written for one agent works in the rest. Optional and experimental fields are where support varies, so treat those as a bonus rather than a foundation. ## Where to go next For the file-level detail — every frontmatter field, and why `description` decides whether your skill ever loads — read [SKILL.md, explained](https://skills.wondel.ai/learn/skill-md-explained/). To choose between a skill, an MCP server and a subagent for a specific job, [Claude skills vs MCP](https://skills.wondel.ai/learn/claude-skills-vs-mcp/) and [skills vs subagents vs prompts](https://skills.wondel.ai/learn/skills-vs-subagents-vs-prompts/) make the call concrete. Or skip the theory and install a few. Our [library of 50 skills](https://skills.wondel.ai/skills/) is free and MIT-licensed: ``` npx skills add wondelai/skills --all --global ``` Then ask your agent to do something one of them covers, and watch it reach for the right method without being told how.