What are agent skills, and how do you write SKILL.md?

What is a skill, and how is it different from a rules file?

As the open standard defines it, a skill is a folder with a SKILL.md file in it. The file starts with at least a name (name) and a description (description), followed by instructions that tell the agent how to do a task. The folder can also hold scripts, reference documents and templates.

Anthropic developed the format. Claude Code added support for skills in version 2.0.20 on 16 October 2025, and Anthropic published the format as an open standard on 18 December 2025. As of 18 October 2026, the skills pages of Claude Code, Codex, Cursor, Gemini CLI and Copilot say they build on this standard. The standard’s own list has 46 products, and the standard’s site says the list shows only some of the products that support it. On 18 June 2026, Google replaced Gemini CLI with Antigravity CLI for free users and Google AI Pro and Ultra subscribers; Gemini CLI remains available with a company licence or a paid API key. Antigravity reads skills too and looks for project skills in .agents/skills.

What sets it apart from a rules file (AGENTS.md, CLAUDE.md, GEMINI.md) is when it is read. A rules file is read from top to bottom in every session. A skill’s instructions are loaded only when a task calls for them. The tools say this in their own words:

• Claude Code: unlike CLAUDE.md, a skill’s body loads only when the skill is used. So long reference material takes up almost no room until it is needed.
• Gemini CLI: context files such as GEMINI.md give the workspace constant background; a skill is expertise that is opened when it is needed.
• Codex: AGENTS.md shapes the agent’s behaviour, and skills package processes that repeat.
• Copilot: simple instructions that apply to almost every task go in custom instructions, and detailed instructions that should be read only when relevant go in a skill.

Older formats are moving to skills too. In Claude Code, the commands under .claude/commands/ have been merged into skills. Codex has deprecated custom prompts and recommends skills instead. Cursor ships a /migrate-to-skills skill that turns rules and slash commands into skills.

We covered rules files in our post on AGENTS.md and CLAUDE.md, commands that run every time in our post on hooks, and helpers that do their work in a separate context in our post on subagents. This post covers the layer in between: instructions the agent opens only when it needs them.

When does the agent read a skill?

The standard calls this progressive disclosure. The agent does not read a skill all at once; it reads it piece by piece, as the task requires:

The first step is paid for in every session, even when the skill is never used. That is why the number of skills you install matters. Two tools say how much room this list gets:

• Claude Code gives the list 1% of the model’s context window. If the list doesn’t fit, it drops the descriptions of the skills you use least. Each description is also cut at 1,536 characters in the list.
• Codex gives the list at most 2% of the context window, or 8,000 characters when it doesn’t know the window. With skills.max_context_tokens you can raise this to at most 10,000 tokens. If many skills are installed, Codex shortens the descriptions first.
• Cursor, Gemini CLI and Copilot: not stated in the documentation.

A skill takes up room after it opens, too. In Claude Code, the content of an invoked skill enters the conversation as a single message and stays there in later turns. When the conversation is compacted, only the first 5,000 tokens of each skill are added back. So write the most important instruction at the top of the file.

Where do you put skills in each of the five tools?

The standard defines what goes inside a skill folder, but not where the folder lives. Its guide for tool developers says so plainly and describes .agents/skills as the shared folder that is catching on across tools. Here is what the five tools’ documentation said on 18 October 2026:

Source: each tool’s skills documentation, 18 October 2026. In these folders each skill sits in a subfolder of its own: .agents/skills/<name>/SKILL.md. Cursor reads Claude Code’s and Codex’s folders for compatibility. Copilot’s personal folders are from the CLI documentation; the VS Code documentation adds ~/.claude/skills to them. “Not stated in the documentation”: in the pages we read that day, we found no sentence that describes this.

No folder appears in the documentation of all five tools. Four tools read .agents/skills; Claude Code’s documentation lists only .claude/skills and says nothing about .agents/skills. Besides Claude Code, Cursor and Copilot read .claude/skills; the Codex and Gemini CLI documentation does not list it. A folder missing from the documentation does not mean the tool never reads it. But if you go by the documentation, no single folder lets you count on a skill opening in all five tools.

The tools also behave differently when two skills share a name. The standard’s guide describes project skills winning over personal ones as the convention all tools share, and the Gemini CLI and Copilot CLI documentation follows it. In Claude Code’s documentation the order is the other way round: the personal skill wins over the project’s. Codex doesn’t merge the two and shows both in the list.

Subfolders are read differently too. Claude Code and Codex read every skills folder from the folder where you started the session up to the repository root. Cursor finds every .cursor/skills or .agents/skills folder inside the repository and suggests the skills there only while you work with files in that folder. Gemini CLI looks only one level deep in a skills folder: .gemini/skills/<name>/SKILL.md is found, anything deeper is not.

How do you use the same skill in all five tools?

If your skills live in .agents/skills, Codex, Cursor, Gemini CLI and Copilot read them; Claude Code needs one more step. The shortest route the documentation backs is this: write the skill under .agents/skills/<name>/ and point .claude/skills/<name> at it with a symlink.

mkdir -p .claude/skills
# the skill lives in .agents/skills/pr-summary/SKILL.md
ln -s ../../.agents/skills/pr-summary .claude/skills/pr-summary
git add .claude/skills/pr-summary

Claude Code’s documentation says a skill folder (.claude/skills/<name>) can be a symlink to a folder somewhere else. Even when several locations point at the same target, it loads the skill once. Turning the whole .claude/skills folder into one symlink is not mentioned; the documentation describes a link per skill. If you link the other way round, Codex’s documentation also says it follows the target of symlinked skill folders.

If a teammate works on Windows, watch out for one thing. According to Git’s documentation, when core.symlinks is off, a symlink is checked out as a small text file that holds the link’s path. And git clone turns that setting off by itself if the file system doesn’t support symlinks. Check separately that the link works on their machine.

We also looked at what popular repositories do. For the AGENTS.md post we had scanned the 100 most-starred repositories on 13 October 2026; this time we looked through the same trees for SKILL.md. Of the 98 repositories whose tree we could read in full, 41 have at least one SKILL.md. Of those, 21 keep their skills in a tool folder at the root:

The most common folder is .agents/skills, the one four tools read. 7 repositories link the two folders with a symlink. 5 point .claude/skills at .agents/skills, 1 goes the other way and points .agents/skills at .claude/skills, and 1 points .claude/skills at Copilot’s .github/skills folder. vercel/next.js and flutter/flutter link the whole .claude/skills folder. langgenius/dify links each skill on its own, which is the way Claude Code’s documentation describes.

What goes at the top of a SKILL.md?

A SKILL.md has two parts: YAML at the very top between two --- lines (the frontmatter), and Markdown instructions below it. The standard defines six frontmatter fields:

Source: the Agent Skills specification, 18 October 2026.

The tools don’t apply these rules equally strictly:

• In Claude Code every field is optional, and only description is recommended. If name is missing, the folder’s name is used. A field it doesn’t recognise is ignored without an error.
• Codex, Cursor, Gemini CLI and Copilot require name and description.
• Gemini CLI silently skips the file if either field is missing or if anything comes before the first --- line (a heading, a comment, even a blank line). It also takes the skill’s name from the name field, not from the folder; the standard and Cursor require the name to match the folder’s name.
• Copilot CLI also allows capital letters, spaces, underscores, dots and colons in the name. The standard accepts only lowercase letters, digits and hyphens.

The rules about XML tags are Anthropic’s, not the standard’s. Under its rules for claude.ai and the API, name and description cannot contain XML tags, and name cannot contain the words “anthropic” or “claude”. Fields that belong to Claude Code (such as when_to_use, context and hooks) work in Claude Code. But if you upload the same skill to claude.ai or the Skills API, any field outside the standard stops the upload: Unexpected key(s) in SKILL.md frontmatter.

If you will use a skill in more than one tool, start with the standard’s fields only. The example below uses only the two required fields and follows the field rules in all five tools’ documentation:

When you decide what goes in the body, ask every line the question from the standard’s guide: would the agent get this task wrong without this instruction? If the answer is no, delete the line. Move long reference material under references/ and link it directly from SKILL.md. Both the standard and Anthropic’s guide recommend keeping reference files one level away from SKILL.md.

What should the description say?

Before it picks a skill, the agent sees only the skill’s description. The standard’s guide says it plainly: “the description carries the entire burden of triggering.” The tools’ documentation says the same: Claude Code, Codex, Cursor and Copilot pick a skill by its description. Gemini CLI’s guide, too, calls the description the only information the model has before it opens the skill.

• Say what it does and when to use it. The standard, Claude Code, Cursor and Copilot ask for both together. A description like “Helps with PDFs.” tells the agent nothing; it is the standard’s own bad example.
• Use the words your users would say. Claude Code’s troubleshooting list starts here: does the description include keywords users would naturally say?
• Put the important part first. When the list doesn’t fit, descriptions get shorter. Claude Code cuts each description at 1,536 characters in the list. Codex shortens descriptions first when many skills are installed, so its documentation recommends putting the use case and the trigger words first.
• Set it apart from similar skills. Gemini CLI’s guide wants descriptions that are distinct from one another and from what the model can already do.

The guides part ways on point of view. Anthropic’s guide asks for the third person and says descriptions that begin “I can help you…” or “You can use this…” can cause discovery problems. agentskills.io’s guide, by contrast, recommends writing the description as an instruction to the agent, with the pattern “Use this skill when…”. Both guides’ own examples take the same path: first what the skill does, then when to use it, with “Use when…”. The example above is written that way too.

Even a good description doesn’t guarantee that the skill opens every time. According to the standard’s guide, agents mostly turn to skills for tasks they can’t handle alone. A one-step request like “read this PDF” may not open a PDF skill even when the description fits perfectly. For Copilot, the VS Code documentation also says discovery does not guarantee that the skill is invoked for every relevant prompt.

Do you call a skill yourself, or does the agent pick it?

Both work. In all five tools, the agent can open a skill on its own when it finds the skill fits the task. Calling a skill by hand, and stopping the agent from picking it on its own, depend on the tool:

Source: each tool’s skills documentation, 18 October 2026. In Claude Code and Copilot, user-invocable: false does the opposite: only the agent can open the skill.

Turn off the agent’s own choice for tasks with side effects. Claude Code’s documentation puts it like this: “You don't want Claude deciding to deploy because your code looks ready.” Skills that deploy, commit or send messages are of this kind. With this setting, Claude Code doesn’t put the skill’s description into the context at all, so it takes no room in the list either. For an example of a skill you call by hand, one that turns a review request into the /review-pr command, see our post on the code review prompt.

Gemini CLI works differently: only the agent can call activate_skill, the tool that opens a skill; you can’t. Instead, the agent asks for your approval every time it opens a skill.

How can you tell whether a skill works?

Claude Code’s documentation starts with a warning: “Seeing a skill trigger tells you Claude found it, not that it did what you intended.” Whether a skill opens and whether it does the job right are two separate questions, and each one is measured on its own.

Both are measured by comparison. Collect a few realistic prompts; run each one in a fresh session, once with the skill turned on and once with it turned off, and put the results side by side. The fresh session matters, because the context built up while you wrote the skill hides the gaps in its instructions.

To measure how often a skill opens, agentskills.io’s guide gives a concrete recipe:

• Write about 20 prompts: half should open the skill and half should not.
• Pick the ones that should not from similar tasks. Prompts that use the same words but ask for something else show best how sharp the description is.
• The model doesn’t make the same decision every time. Run each prompt several times (3 is a good start) and work out how often the skill opened.
• A threshold of 0.5 is reasonable: the rate should be above it for the prompts that should open the skill, and below it for those that should not.

That is why a single try does not count as a result. It is normal for the same prompt to open the skill on one run and not on the next; when you change a description, run the same prompts the same number of times again.

What should you check before installing someone else’s skill?

A skill is not just text: it can run scripts, let some tools be used without asking, and steer the agent with its instructions. Anthropic’s documentation says a malicious skill can lead the agent to call tools or run code in ways that don’t match the skill’s stated purpose, and recommends using skills only from sources you trust.

The tools handle trust differently:

• Claude Code applies a project skill’s allowed-tools field even in a -p run in a folder you have never trusted. That is why its documentation asks you to read this field in skills checked into a repository before you run Claude Code there. The field restricts no tools; it lets the listed tools be used without asking during the turn in which the skill is invoked.
• Copilot says skills installed with gh skill are not verified by GitHub and may contain prompt injection, hidden instructions or malicious scripts. It recommends looking at a skill with gh skill preview before you install it.
• Gemini CLI asks you to confirm the source when you install from a remote address, and asks for permission every time it opens a skill. It also loads project skills under .gemini/skills only when the workspace folder is marked as trusted.
• Codex and Cursor have no rule about trust on their skills pages: not stated in the documentation.

The standard’s guide for tool developers also recommends loading project skills only in folders marked as trusted. A repository you have just cloned can add instructions to the agent’s context without you noticing.

Should you use a skill or AGENTS.md?

Neither replaces the other, and popular repositories use both. Of the 41 repositories we scanned that have a SKILL.md, 35 also have an AGENTS.md or a CLAUDE.md at the root.

What decides it is when the information is needed. Put what applies to every task (the project’s structure, build commands, “never do this” rules) in the rules file, and a workflow you need now and then, or a long reference text, in a skill. The test in Claude Code’s documentation works well: if a section of CLAUDE.md has stopped being a fact and turned into a procedure, make it a skill.

Vercel put this question to its own evals in a post dated 27 January 2026. In evals built on Next.js 16 APIs, the skill was never invoked in 56% of cases. An 8 KB docs index embedded in AGENTS.md reached a 100% pass rate, and the skill’s best result was 79%. This is one team’s measurement on one topic, and the post doesn’t say how many tasks it was measured on. Vercel’s own conclusion is not “one or the other” either: “The two approaches complement each other.” According to the post, specific workflows that the user starts explicitly work better as skills.

A rule that every pull request must follow is also a job for the rules file. When diffox reviews a pull request, it reads the AGENTS.md at the repository’s root, or CLAUDE.md if there is none, and uses the rules in it as review rules. If you want a rule to hold in every review, write it in the rules file.