What are agent skills? How SKILL.md works, tool by tool

What an agent skill is

An agent skill is a set of instructions for one particular kind of task, saved as a folder. It's like a guide for a new colleague on how your team reviews code, which the agent opens only when that task comes up.

Every skill folder contains a file called SKILL.md. It begins with a short header that gives the skill a name and a description, and the instructions follow in ordinary Markdown. The folder can also hold scripts the agent can run, longer reference documents and templates.

Anthropic introduced Agent Skills for Claude in October 2025 and published the format as an open standard that December. Many other agents have adopted it since, so one skill can work across several tools.

A tiny SKILL.md, line by line

Each numbered item below is one line of a complete skill, saved as SKILL.md inside a folder named release-notes.

1. ---
2. name: release-notes
3. description: Writes release notes from merged pull requests. Use when someone asks for release notes or a changelog.
4. ---
5. List the pull requests merged since the last release tag.
6. Group them under Added, Fixed and Changed, one short line each.

The lines between the dashes form the header, where the name should match the folder name in lowercase letters, numbers and hyphens. Anthropic limits names to 64 characters and descriptions to 1,024. The description should explain what the skill does and when to use it, because it's the only part the agent sees at first.

How do agent skills work?

Agents load skills in three stages, which Anthropic calls progressive disclosure, so a long list of skills doesn't crowd the conversation.

1. At the start, the agent reads every skill's name and description, which Anthropic estimates at about 100 tokens per skill.
2. When your request matches a description, the agent opens the full SKILL.md. Anthropic's docs size those instructions at under 5,000 tokens.
3. While it works, the agent reads other files only when the instructions point to them. When it runs a script, only the output enters the conversation.

You can also start a skill yourself. In Claude Code, Cursor and Kiro, you type a slash and the skill's name, as in /release-notes, while Codex uses a dollar sign. Claude Code, Cursor and Codex can also switch off automatic use, so a skill runs only when you call it.

How a skill differs from a prompt

A prompt is something you type for one task in one conversation, and next time you type or paste it again. A skill is saved once and loads automatically whenever a task matches its description.

A skill can also carry files. A script inside the folder performs a job identically every time, so the agent doesn't improvise new code. Long reference documents use no space until the agent opens them.

A rules file such as CLAUDE.md or AGENTS.md is different again: it holds standing rules for a whole project, as Kiro's steering files do. An MCP server connects the agent to an application or a data source, while a skill teaches the procedure for one kind of task. For more on that split, see MCP vs skills vs plugins.

Which tools support agent skills, and where they are stored

These are the main folders each tool reads, from each maker's documentation on Nov 8, 2026. A path beginning with ~ sits in your home folder, and the others sit inside your project. For step-by-step setup, see how to install skills in Claude Code, Codex and Cursor.

Tool	Project skills	Your own skills	Start one yourself
Claude Code	.claude/skills	~/.claude/skills	/skill-name
Claude	No folder	Upload a .zip	Claude picks it
Codex	.agents/skills	~/.agents/skills	$skill-name
Cursor	.cursor/skills or .agents/skills	~/.cursor/skills or ~/.agents/skills	/skill-name
GitHub Copilot	.github/skills or .agents/skills	~/.copilot/skills or ~/.agents/skills	Copilot picks it
Kiro	.kiro/skills	~/.kiro/skills	/skill-name
Antigravity	.agents/skills	~/.gemini/config/skills	/skill-name
OpenCode	.opencode/skills	~/.config/opencode/skills	@skill-name
goose	.agents/skills	~/.agents/skills	/skills in the CLI

Skills in each tool

2. Claude apps: upload a skill as a .zip

• ClaudeUpload your own, or use the built-in onesFree

Turn on code execution, then upload your skill as a .zip file under Customize > Skills. Claude also includes built-in skills for Word, Excel, PowerPoint and PDF files, but skills you add here don't sync to Claude Code.

3. Codex: two skills built in

• CodexBuilds and installs skills for youFree

Codex checks .agents/skills in every folder from your current location up to the repository root. Its built-in skill-creator drafts a new skill from a plain description, and skill-installer adds ready-made ones.

4. Cursor: reads other tools' folders too

• CursorLoads Claude Code and Codex skills as wellFree

Cursor also loads skills from the folders Claude Code and Codex use, so skills you already have may simply work. Type a slash in the agent chat to attach one to a message.

5. GitHub Copilot: skills on GitHub and in your editor

• GitHub CopilotWorks in the CLI, on GitHub and in VS CodeFree

Copilot also reads .claude/skills inside a repository and chooses a skill from its description. Skills work in Copilot CLI, the cloud agent, code review on GitHub and agent mode in Visual Studio Code.

The one folder most agents read

Six of the eight tools with folders above read .agents/skills: Codex, Cursor, GitHub Copilot, Antigravity, OpenCode and goose. Mistral Vibe CLI, Kilo Code, Qwen Code and OpenClaw read it as well. Manus accepts skills as uploads or imports them from GitHub instead.

Claude Code and Kiro use only their own folders. If you combine Claude Code with other agents, keep project skills in .claude/skills, which Cursor, GitHub Copilot, OpenCode and goose also read.

Treat a skill like software you install

A skill can instruct an agent to run code, so a malicious one can do real damage, such as leaking private data. Anthropic recommends using skills only from trusted sources and reading every file first, scripts included, with extra care for skills that retrieve internet content.

Claude Code applies a project skill's pre-approved tools even in folders you haven't trusted, so review them before running it in an unfamiliar repository. GitHub warns against pre-approving shell access unless you trust the skill's source.

How we checked

We read the official documentation on skills from Anthropic, OpenAI, Cursor, GitHub, Kiro, Google, OpenCode and goose on Nov 8, 2026. We list a tool only where its maker's documentation says it reads SKILL.md files.

We haven't tested these tools side by side: everything here comes from the makers' own pages. When a folder or command changes, we update this page and its date.

Questions people ask