An agent skill is a folder of instructions that teaches an AI agent how to do a specific job. Its one required file, SKILL.md, holds a name, a description and the steps to follow. The agent reads the name and description at the start, then loads the full instructions only when a task matches. The format began at Anthropic and is now an open standard used by Claude Code, OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot and others, so one skill can work across several agents. This guide explains how skills work, where each agent keeps them and how to write your first one.
Key facts
- What it is: a folder with a SKILL.md file of instructions, plus optional scripts and templates
- Standard: Agent Skills, developed by Anthropic and published as an open standard on 18 December 2025
- How it loads: about 100 tokens per skill at start-up; the full instructions load only when needed
- Where it works: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Antigravity, OpenCode, Hermes Agent and more
- Cost: skills are free text files; you pay for the agent and model, if at all
- Safety: a skill runs with your agent's access, so check it before you install it
On this page
- What is an agent skill?
- How do agent skills work?
- Which AI agents support skills?
- How to install an agent skill
- How to write your first skill
- Skills vs MCP, plugins and custom instructions
- Which agent skills are popular?
- Are agent skills safe?
- Frequently asked questions
What is an agent skill?
Think of a skill as a written procedure for a new colleague. A good AI model is clever but knows nothing about how your team writes minutes, reviews code or chases an invoice. A skill gives it that procedure, once, so you stop pasting the same instructions into every chat.
The Agent Skills site at agentskills.io calls this a "lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows". In practice it is a folder:
meeting-notes/
SKILL.md required
scripts/ optional: code the agent can run
references/ optional: extra documents
assets/ optional: templates and filesOnly SKILL.md is required. The folder can stay that simple for years, or grow into a small toolkit with scripts the agent can run. Our weekly chart of the top agent skills shows both ends: one chart entry, andrej-karpathy-skills, is a single text file, while others bundle dozens of skills and their own tools.
How do agent skills work?
Agent skills work by loading in stages, which the standard calls progressive disclosure. This is why you can keep many skills installed without filling the agent's memory.
| Stage | When | What loads | Typical size |
|---|---|---|---|
| Discovery | At start-up | The name and description of every skill | About 100 tokens per skill |
| Activation | When a task matches a description | The full SKILL.md instructions | Under 5,000 tokens recommended |
| Execution | Only if the instructions call for it | Scripts, references and templates | Depends on the files used |
Figures are from the Agent Skills specification. A token is roughly three quarters of an English word, so 40 installed skills cost about 4,000 tokens before you type anything. That is small on a big cloud model, and it matters more on a small local model.
The description does the heavy lifting. It is how the agent decides whether a skill applies, so a vague description means a skill that never runs. In most agents you can also call a skill by name: /skill-name in Claude Code, or $skill-name in Codex.
Which AI agents support skills?
At least eight widely used agents read the SKILL.md format, and the folder they look in is the main difference. The table shows where each one looks, from each vendor's documentation on 6 November 2026.
| Agent | Project folder | Personal folder |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| OpenAI Codex | .agents/skills/ | ~/.agents/skills/ |
| Cursor | .agents/skills/ or .cursor/skills/ | ~/.agents/skills/ or ~/.cursor/skills/ |
| Gemini CLI | .agents/skills/ or .gemini/skills/ | ~/.agents/skills/ or ~/.gemini/skills/ |
| GitHub Copilot | .agents/skills/, .github/skills/ or .claude/skills/ | ~/.agents/skills/ or ~/.copilot/skills/ |
| Google Antigravity | .agents/skills/ | ~/.gemini/config/skills/ |
| OpenCode | .agents/skills/, .opencode/skills/ or .claude/skills/ | ~/.agents/skills/, ~/.config/opencode/skills/ or ~/.claude/skills/ |
| Hermes Agent | None listed | ~/.hermes/skills/ |
The useful pattern: .agents/skills/ in a project is read by six of these eight agents. If your team uses more than one agent, start there. Claude Code is the main exception and uses .claude/skills/, which Copilot and OpenCode read too.
Two cases sit outside the table. LM Studio Bionic uses the same format and says it can use compatible skills from Codex and Claude Code. In ChatGPT, OpenAI says standalone skills work in the desktop app, Codex CLI and IDE extension, while skills bundled in a plugin also reach Chat and Work on the web and mobile. For claude.ai and the Claude app, see Claude skills explained.
How to install an agent skill
There are three common ways to install a skill. Check who published it first, using our five-point safety check.
- Use the skills command: Vercel's free tool installs a GitHub repo into most agents with
npx skills add owner/repo. It needs Node.js. Our skills.sh review covers what it does and its limits. - Copy the folder: download the skill, then move the folder containing SKILL.md into one of the locations in the table above.
- Use your agent's own store: Claude Code has a plugin directory, Cursor has a marketplace, and Codex has
$skill-installer.
Then ask your agent to do the job in plain English and see whether it uses the skill. For the exact commands in Claude Code, including how to list and remove skills, see how to install and use skills in Claude Code.
How to write your first skill
You can write a working skill in about ten minutes with no code. This example turns rough notes into minutes.
- Make a folder. Create a folder named after the skill, such as meeting-notes, inside .agents/skills/ or your agent's own skills folder.
- Create SKILL.md. Add a file called SKILL.md to that folder.
- Add a name and description. Between two lines of three hyphens, add a name that matches the folder and a description saying what the skill does and when to use it.
- Write the instructions. Below the settings, write the steps the agent should follow, in plain Markdown.
- Test it. Ask for the job in plain English, without naming the skill, and check that the agent picks it up.
Here is the finished SKILL.md:
---
name: meeting-notes
description: Turns rough meeting notes into minutes with decisions, actions and owners. Use when the user pastes notes or asks for minutes.
---
# Meeting notes
1. List who attended, if the notes say.
2. Write the decisions as short bullet points.
3. Put actions in a table: action, owner, due date.
4. If an owner or date is missing, write "not agreed". Never guess.
5. Use British spelling.The standard sets a few firm rules, and breaking them is the usual reason a skill does not load:
- Name: up to 64 characters, lowercase letters, numbers and single hyphens only, and it must match the folder name.
- Description: up to 1,024 characters, saying what the skill does and when to use it. Include the words people actually type.
- Length: keep SKILL.md under 500 lines and move long reference material into separate files.
Three habits make a good skill better. Write down what you would tell a new colleague, including the mistakes people make. Say what to do when information is missing, as step 4 does. And stick to the standard fields if you want the skill to move between agents, because extras such as Claude Code's disable-model-invocation belong to one product.
If you would rather not start from a blank page, Codex has a built-in $skill-creator, Cursor has /create-skill, and Anthropic publishes a skill-creator plugin.
Skills vs MCP, plugins and custom instructions
A skill is one of several ways to extend an agent, and the names overlap. This is the quick version:
| Feature | What it does | When it loads | Use it for |
|---|---|---|---|
| Agent skill | Teaches a procedure | Description at start, the rest on demand | Repeatable jobs and house style |
| MCP server | Connects to an outside service | Depends on the agent | Live data and actions in other apps |
| Custom instructions (such as CLAUDE.md) | Sets standing rules | Every session | Short rules that always apply |
| Plugin | Packages skills, MCP servers and more | When installed and enabled | Sharing a whole set-up |
The one people ask about most is MCP. We compare them properly in agent skills vs MCP.
Which agent skills are popular?
Design and engineering-method skills lead right now. In the week to 4 November 2026, the most GitHub stars went to impeccable, a design skill, with 9,588 new stars, followed by claude-mem and unslop. Our top 20 agent skills chart updates every Thursday and profiles every skill that has made the list, with what it does and how to install it.
Stars measure attention, not quality or safety. Treat the chart as a list of things worth a look.
Are agent skills safe?
Agent skills are mostly safe, but installing one is closer to installing an app than reading a document. A skill runs with whatever your agent can reach, including files and keys, and fake skills have already been used to steal credentials. Check who published it, read every file and start with skills from people you recognise. Are agent skills safe to install? has the full five-point check.
If you use one at work, the skill itself rarely raises a data protection question, but what it tells the agent to read might. See AI agents and UK GDPR.
Frequently asked questions
What is an agent skill?
An agent skill is a folder containing a SKILL.md file: a name, a description and written instructions that an AI agent follows for one kind of job. It can also hold scripts, templates and reference files. The agent reads only the name and description at the start, then loads the rest when a task matches.
What is SKILL.md?
SKILL.md is the one required file in an agent skill. It opens with a short block of settings, which must include a name and a description, followed by instructions in plain Markdown. The format is defined by the Agent Skills open standard at agentskills.io.
Who created agent skills?
Anthropic developed the format and published Agent Skills as an open standard on 18 December 2025. It is now used by tools from other companies, including OpenAI Codex, Cursor, GitHub Copilot and Google's Gemini CLI and Antigravity.
Are agent skills free?
Yes. A skill is a set of text files, and most public skills are free to download. You still need an agent to run it, which may need a paid plan. A skill may also call a paid service of its own, so check its README. Running a free agent with a local model costs nothing extra.
Do I need to code to use agent skills?
No. Many skills are plain English instructions, and writing a simple one needs no code. You do need to be comfortable putting a folder in the right place or running one install command. A skill that bundles scripts is worth reading carefully, or asking someone technical to check.
What is the difference between agent skills and MCP?
A skill teaches an agent how to do something. MCP connects an agent to an outside service, such as a database or Slack. They work well together: MCP reaches the system and a skill sets out how your team uses it.
Will the same skill work in Claude Code and Codex?
Usually, because both follow the same open format. A skill built only on the standard fields should move across unchanged. Vendor-specific extras, such as Claude Code's shell lines, may not work elsewhere, and scripts depend on what is installed on your computer.
Read next
- Top 20 agent skills this week
- Agent skills vs MCP
- Agent skills on local models
- Are agent skills safe to install?
- How to install and use skills in Claude Code
- Claude skills explained
Sources
- Agent Skills overview - checked 6 November 2026
- Agent Skills specification - checked 6 November 2026
- Equipping agents for the real world with Agent Skills, Anthropic - checked 6 November 2026
- Extend Claude with skills, Anthropic docs - checked 6 November 2026
- Build skills, OpenAI docs - checked 6 November 2026
- Agent Skills, Cursor docs - checked 6 November 2026
- Agent skills, Gemini CLI docs - checked 6 November 2026
- About agent skills, GitHub docs - checked 6 November 2026
- Agent skills, Google Antigravity docs - checked 6 November 2026
- Agent skills, OpenCode docs - checked 6 November 2026
- Skills system, Hermes Agent docs - checked 6 November 2026
