Agent skills explained: what they are and how to use them

You have typed the same release checklist into your agent's chat more than once. Agent skills are how you stop: a folder with a SKILL.md file that teaches your coding agent one job, which it loads only when a task calls for it.

The short answer to "how do I add one to Claude Code" is this. Create .claude/skills/<name>/SKILL.md in your repository, or ~/.claude/skills/<name>/SKILL.md to have it in every project. Give it a name and a description. Claude uses the skill when your request matches the description, or when you type / and its name. The rest of this guide covers the format, why installing many skills costs little, installing them from a marketplace, and which folders other agents read.

What agent skills are

A skill packages the instructions for one task, plus any scripts or reference files the task needs: writing a database migration, preparing a release, reviewing a pull request against your team's checklist.

That sets it apart from the instruction files you may already have. AGENTS.md or CLAUDE.md holds facts the agent needs on every request, such as commands, layout and rules, and loads at the start of every session. A skill holds a procedure the agent needs some of the time, and its body loads only when it is used.

Claude Code's docs draw the line in a useful place: when a section of your instruction file has grown into a procedure rather than a fact, move it into a skill. If you are still setting up the instruction file itself, start with the AGENTS.md guide.

A skill is also different from a saved prompt. One you commit lives in your repository, goes through code review like any other file, and reaches every teammate and every session.

The format started at Anthropic, which released it as an open standard called Agent Skills, with the spec at agentskills.io. Claude Code, OpenAI Codex, Cursor and GitHub Copilot all read it, so one skill folder can work in several agents.

What goes in a SKILL.md file

A skill is a folder named after the skill. The only required file is SKILL.md; next to it you can keep scripts/, references/ and assets/ folders.

SKILL.md starts with YAML frontmatter. The spec requires two fields:

• name: up to 64 characters of lowercase letters, numbers and hyphens, matching the folder name.
• description: up to 1,024 characters, saying what the skill does and when to use it.

The optional fields are license, compatibility, metadata and an experimental allowed-tools. Below the frontmatter, the body is ordinary Markdown with the steps to follow.

---
name: write-migration
description: Writes and checks a database migration. Use when the user asks to add or change a table, column, index or constraint.
---

# Write a migration

1. Read `db/schema.sql` and the three newest files in `db/migrations/`.
2. Create `db/migrations/<timestamp>_<change>.sql`. Never edit a migration that has already run.
3. Make the change reversible, or explain in the file why it can't be.
4. Run `pnpm db:migrate && pnpm test:db` and fix failures before you continue.
5. Report the new file and any data the change could lose.

Naming rules and index patterns: [references/conventions.md](references/conventions.md)

The description does most of the work, because it is what the agent matches your request against. Put the main use case and the words people actually type first, since tools shorten descriptions when many skills are installed.

Claude Code reads more fields than the spec defines. Two are worth knowing early: disable-model-invocation: true stops Claude from starting the skill on its own, which is what you want for a deploy, and paths limits a skill to files that match a pattern. Fields like these go beyond the standard, and support varies by tool. An upload to claude.ai or the Claude API fails on any field outside the spec, so stick to the spec's fields for a skill you will use beyond Claude Code.

Why installing many skills costs little

Skills load in stages, which Anthropic's docs call progressive disclosure:

1. At startup, the agent reads only each skill's name and description, about 100 tokens a skill.
2. When a request matches, it reads the body of SKILL.md. Keep that under 500 lines.
3. Files the body points to load only if the task needs them. Scripts run without their code entering the context window; only their output does.

So a long list of installed skills costs little until one runs. The real cost of a big collection is wrong matches. Two skills with vague, overlapping descriptions get picked at the wrong moment, and once the list outgrows its budget, Claude Code drops the descriptions of the skills you use least. Say exactly when each skill applies, and move long reference material into separate files one level below SKILL.md. Anthropic's overview shows the loading in detail.

How to add agent skills to Claude Code

There are three ways to give Claude Code a skill:

1. In your repository. Save it as .claude/skills/<name>/SKILL.md and commit it, so everyone who clones the repo gets it. In a monorepo, a .claude/skills/ folder inside a package loads once Claude works on files there.
2. For yourself. ~/.claude/skills/<name>/SKILL.md is available in all your projects on that machine.
3. From a marketplace. Claude Code installs shared skills as part of plugins. Anthropic's official marketplace is registered the first time you start an interactive session, and /plugin lets you browse it. To add another, pass its GitHub repository to /plugin marketplace add. Anthropic's example skills install like this:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Skills from a plugin are namespaced, so you run them as /plugin-name:skill-name.

Once a skill is in place, Claude picks it when your request matches its description. To run one yourself, start your message with / and its name. Claude Code watches the skill folders, so an edit to SKILL.md applies in the session you have open. If a skill never triggers, check that its description uses the words you would actually type, ask Claude "What skills are available?", and try running it by name. Claude Code's skills docs cover the rest, including running a skill in a subagent.

Claude agent skills are not limited to the terminal, either. On claude.ai you can upload a skill as a zip file, and the Claude API runs skills with its code execution tool.

AI agent skills in Codex, Cursor and Copilot

The SKILL.md format is the same everywhere. What differs is the folder each agent reads:

The gap to notice: Claude Code doesn't read .agents/skills/, and Codex doesn't read .claude/skills/. A copy in .claude/skills/ reaches Claude Code, Cursor and Copilot; Codex needs one in .agents/skills/. If your team uses Claude Code and Codex, keep the two folders in step, either with symlinks (both agents follow them, but symlinks can break in Windows checkouts) or with a script that copies the files and checks they match.

Starting a skill by hand differs too. In Codex you type $ and the skill name, or run /skills. In Cursor you type / in Agent chat. Copilot chooses skills from their descriptions. Codex's skills docs and Cursor's list every location they scan.

Where to find skills, and what to check first

There is no single agent skills marketplace. Each tool has its own way in:

• Claude Code: plugin marketplaces. The official one is built in, and any repository with a .claude-plugin/marketplace.json file can be added as another.
• Codex: $skill-installer adds curated skills, or skills from another repository.
• GitHub CLI: gh skill, in public preview, searches GitHub repositories for skills, previews one and installs it, including for agents other than Copilot.
• Cursor: skills from a GitHub repository come in as a plugin. Import a repository that has a .cursor-plugin/marketplace.json, or add it as a team marketplace.

Whatever the source, read a skill before you install it. A skill is instructions and code that your agent will follow and run. Anthropic's advice is to use skills only from sources you trust and to audit everything in the folder: the SKILL.md, the scripts, and anything that fetches from a URL. GitHub warns that the skills gh skill finds are not verified and can carry hidden instructions, so preview them first. In Claude Code, check the allowed-tools line of skills in any repository you clone, because Claude Code applies it even in a folder you have never trusted.

Check the licence too. Many of the example skills in Anthropic's repository are Apache-2.0, but its document skills are source-available, not open source.

The skills that come with shipanysaas

shipanysaas, the SaaS starter kit this blog belongs to, ships 49 ready-made skills, seven of them for the phone app in the All-in plan. The same copies sit in .claude/skills/, .agents/skills/ and .cursor/skills/, which covers Claude Code, Codex, Cursor and Copilot.

Nine are part of the kit itself, such as postgres-expert for schema and policy changes and rls-review for auditing row-level security with tests that try to cross between accounts. The other 40 are third-party skills from teams such as Supabase, Stripe and Expo, kept with their MIT or Apache-2.0 licence files. A manifest, tooling/scripts/src/agent-skills.json, records where each one came from, and pnpm skills:check fails if the three folders drift apart or a licence file is missing. The full list is on the Agent skills docs page.

Frequently asked questions

Are agent skills the same as AGENTS.md or CLAUDE.md?

No. Instruction files load in every session and hold facts: commands, layout, rules. Skills hold procedures and load only when a task needs them. A good split is "run pnpm test before you finish" in AGENTS.md and "how we cut a release" in a skill.

Do I need the name field?

Write it. The open standard requires name and description, Codex requires both, and Cursor requires the name to match the folder. Claude Code falls back to the folder name, but the other tools expect the field.

Do installed skills slow the agent down?

Not much. Until a skill runs, only its name and description are in context. The cost shows up as wrong matches when descriptions are vague or overlap, so say exactly when each skill applies.

Can I use the same skill in Claude Code and Codex?

Yes. The SKILL.md is the same file. Claude Code reads it from .claude/skills/ and Codex from .agents/skills/, so keep a copy, or a symlink, in each. Features only Claude Code supports, such as its extra frontmatter fields, won't carry over.