Every team that uses a coding agent eventually writes the same document three times: once as a README nobody reads, once as a wall of instructions pasted into a system prompt, and once as a Slack message explaining why the agent did it wrong again. Agent skills are the fix for that, and they have quietly become the most important file format in AI-assisted development this year. This guide explains what a skill is, how agents load one, and how to write a skill that changes what your agent does rather than one that it skims and ignores.
What an agent skill is
A skill is a folder. At its centre is a file called SKILL.md: a short block of YAML frontmatter with a name and a description, followed by Markdown instructions. Around it, optionally, sit scripts the agent can run, reference documents it can read, and assets such as templates.
Anthropic introduced the format for Claude in October 2025 and published it as an open standard, documented at agentskills.io, in December 2025. Since then other coding agents have adopted the same format, including OpenAI Codex, Gemini CLI, GitHub Copilot and Cursor, each reading skills from its own folder. The practical result is that a skill your team writes once can travel between tools instead of being rewritten as each vendor's rules file.
The idea is not new — teams have always written down how they work. What is new is a standard shape that an agent knows how to find, decide on, and load at the right moment.
Progressive disclosure: why skills do not flood the context window
The design decision that makes skills work is that the agent does not read them all. At the start of a session it sees only each skill's name and description — a line or two per skill. Only when a task matches a description does the agent load the full SKILL.md, and only when the instructions point to a script or reference file does it open that.
The specification describes this as three stages: discovery, activation and execution. The consequence for you is that you can have dozens of skills installed without paying for them in every request, which is exactly what goes wrong when the same knowledge is pasted into a system prompt.
It also means the description is the most important line you will write. It is the only part the agent sees when deciding whether the skill applies. A vague description such as "helps with database work" will either never trigger or trigger for everything.
Skill, MCP server, or system prompt: which one you need
These three get confused because each can change what an agent does. They solve different problems.
- A system prompt is for things that are true in every request: the agent's role, its tone, rules that must never be broken. Keep it short; everything in it is paid for on every turn.
- An MCP server gives the agent new capabilities — a way to query your ticket system, call an internal API or read a database. It is about access, not about judgement.
- A skill gives the agent procedural knowledge: how your team does a particular job. How to write a migration here, how to cut a release, which test command to run and how to read its output. It is about method.
- The common combination is both: an MCP server that exposes your deployment API, and a skill that explains your team's release checklist and when to stop and ask a human.
Anatomy of a skill that gets used
A useful SKILL.md is shorter than people expect and more specific than they are comfortable with. Write it the way you would brief a capable new colleague who has never seen your codebase.
- Name: lowercase, hyphenated, describing the job — "write-db-migration", not "database-helper".
- Description: when to use it, in the agent's terms. "Use when adding or changing a database table, column or index in this repository." Include the trigger words a user would actually type.
- Steps: the procedure in order, including the commands. "Run the migration generator, never hand-write the file. Then run the migration test suite and read the output before continuing."
- Stop conditions: when the agent must not proceed alone. "If the migration drops a column that holds data, stop and ask."
- Checks: how the agent knows it is done. A command whose output it can verify beats an instruction to "make sure it works".
- References: link to longer documents in the skill folder rather than pasting them in, so they load only when needed.
Where skills live, and sharing them across a team
Most agents distinguish between personal skills, stored in your home directory and available in every project, and project skills, stored in the repository and shared with everyone who clones it. In Claude Code, for example, a project skill lives at .claude/skills/<name>/SKILL.md. Other tools read the same format from their own directories; check each tool's documentation for the path.
Put team procedures in the repository, under review like any other code. A skill is executable knowledge: a wrong instruction in it will be followed confidently, by every developer's agent, until someone notices. Review skill changes as carefully as you review the scripts they call.
The same caution applies to skills downloaded from public collections. A skill can include scripts that the agent will run. Read a third-party skill before installing it, exactly as you would read a shell script before piping it to bash.
How to tell whether a skill is working
The failure you are guarding against is silent: the agent does the task the old way and nobody notices the skill was never loaded. Test it the way you would test a function.
- Write three or four prompts a real developer would type, and confirm the skill activates for each. If it does not, rewrite the description, not the steps.
- Write one prompt that is close but should not trigger it, and confirm it does not. Over-eager skills are as harmful as silent ones.
- Run the full task and check the stop conditions fire: give it the destructive case and confirm the agent asks instead of acting.
- Re-test after editing. A one-word change to the description can change when a skill loads.
A worked example: a release skill
Here is the shape of a skill for a team that releases a web service by tagging the main branch. The frontmatter gives it the name "cut-release" and the description "Use when the user asks to release, ship, tag or deploy a new version of this service. Covers changelog, version bump, tag and post-release checks." Notice that the description names the words people actually say — release, ship, tag, deploy — because those are what the agent matches against.
The body is a numbered procedure. First, confirm the working tree is clean and on the main branch; if not, stop and say why. Second, run the full test suite with the project's test command and read the summary line — if anything failed, stop. Third, collect merged pull requests since the last tag and draft the changelog entry in the house format, with a link to the format file in the skill folder. Fourth, bump the version with the project's script rather than by editing files. Fifth, show the human the changelog and the new version and wait for an explicit go-ahead. Sixth, create and push the tag. Seventh, run the smoke-test script in the skill folder against the deployed version and report its output verbatim.
Three details carry most of the value. The stop conditions are written as hard rules with reasons, so the agent does not talk itself past them. The human confirmation sits before the one irreversible step, the tag push, and nowhere else, so it is not ignored as noise. And the final check is a script whose output the agent reports rather than interprets, so a failed smoke test cannot be summarised as "looks good".
Common mistakes
Most skills that disappoint fail in one of a few predictable ways.
- Writing an essay. Long background sections bury the steps; the agent follows the first plausible instruction it finds.
- Duplicating the system prompt. Rules that apply everywhere belong in one place, not copied into every skill.
- One skill for everything. A "backend" skill that covers migrations, releases and on-call is too broad to trigger reliably; split it by job.
- Instructions without checks. "Make sure the tests pass" invites the agent to assume they did. Give it the command and the line of output that proves it.
Key takeaways
- 1.A skill is a folder with a SKILL.md: a name and description up front, instructions and optional scripts behind them.
- 2.Agents see only the name and description until a task matches — so the description decides whether the skill is ever used.
- 3.Use a system prompt for rules, an MCP server for access, and a skill for method; they combine rather than compete.
- 4.Keep team skills in the repository and review them like code: an agent will follow a wrong instruction confidently.
- 5.Test that a skill activates for real prompts and stays quiet for near-misses.