Skills for coding agents

An agent skill is a folder with a SKILL.md file that teaches an AI coding agent how to do one job the same way every time. The file has a short description that tells the agent when to use it and a body of instructions it reads only when needed. Claude Code, Codex, Gemini CLI, Cursor and VS Code with Copilot all load them. We checked each agent's docs on 31 October 2026.

Quick facts

What a skill is, in plain words

You have a procedure you keep pasting into chat. Maybe it is "how we write release notes", "how to review a pull request here" or "the exact steps to build a PDF report". A skill saves that procedure once, with a name and a one-line description of when it applies.

The agent sees only the name and description at the start of a session. When your request matches, it opens the full file and follows it. That is called progressive disclosure, and it is why you can keep many skills installed without filling the context window. Claude Code's docs put it this way: unlike CLAUDE.md content, a skill's body loads only when it is used, so long reference material costs almost nothing until you need it.

A skill is not the same as three other things people mix it up with:

Rule of thumb from Claude Code's docs: create a skill when you keep pasting the same checklist into chat, or when a section of CLAUDE.md has grown from a fact into a procedure.

The SKILL.md format

A minimal skill, taken from Claude Code's own getting-started example, looks like this:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice.

Save it at ~/.claude/skills/summarize-changes/SKILL.md. Ask "what did I change?" and Claude loads it, or type /summarize-changes to call it directly. The line starting with ` ! `` is Claude Code's dynamic context injection: it runs the command and puts the output into the skill before Claude reads it.

Frontmatter fields that matter

Claude Code accepts a long list of fields. All are optional; only description is recommended. The ones you will use most:

Outside Claude Code, only the fields in the open spec are portable. Claude Code ignores a field it does not recognize without an error, so a typo in a field name fails silently. Check spelling, including hyphens.

Add supporting files

A skill folder can hold more than one file. The standard layout:

my-skill/
  SKILL.md          required: metadata and instructions
  scripts/          optional: code the agent can run
  references/       optional: long docs it reads on demand
  assets/           optional: templates

Keep SKILL.md short and point to the other files. That keeps the always-loaded cost low.

Where each agent loads skills

The shared .agents/skills/ path is the useful discovery. Put a skill there and four of the five agents above will find it. Claude Code is the exception in what we read: its docs list .claude/skills/, so keep a copy or a symlink there. Claude Code supports symlinked skill folders.

Start here: sources of skills

Skills live in repos. These are the ones to know, with what we saw on 31 October 2026.

Anthropic's README carries a clear caution: the skills in that repo are for demonstration and educational purposes, behavior can differ from what Claude gives you, and you should test in your own environment. The document skills (docx, pdf, pptx, xlsx) are described as source-available rather than open source, while many others are Apache 2.0. Check the license on the folder you copy.

Our picks by job

These links go to pages in this directory.

Install a skill, step by step

By hand, any agent

1. Find a skill folder on GitHub.
2. Read SKILL.md and every file in scripts/.
3. Copy the folder into the right path from the table above.
4. Start a new session, or reload.
5. Ask something that matches the description and check that it loaded.

Example for Claude Code, personal scope:

git clone https://github.com/anthropics/skills ~/work-artifacts/scratch/skills
mkdir -p ~/.claude/skills
cp -R ~/work-artifacts/scratch/skills/skills/webapp-testing ~/.claude/skills/

Clone to a scratch folder first, read it, then copy. Do not clone straight into your skills directory.

With the plugin marketplace (Claude Code)

Anthropic's README gives the commands:

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

After install you can just name the task: "Use the PDF skill to extract the form fields from this file."

With the Gemini CLI

gemini skills list --all
gemini skills install https://github.com/user/repo.git --consent

Both commands are in the Gemini CLI docs. --consent confirms the install.

With Codex

Use $skill-installer inside Codex to add curated skills, for example $skill-installer linear. Codex also reads skills from the .agents/skills folders. Restart Codex after changing ~/.codex/config.toml.

Skills with the npx skills tool

Slack's docs, for one, tell users to install skills for other agents with npx skills add <repo> -y -a <agent>. That is a third-party tool from the vercel-labs organization, so read what it does before you use it.

Write your first skill

Five rules, drawn from Claude Code's docs and the open standard:

1. One job per skill. "Write release notes" is a skill. "Handle releases" is a folder of skills.
2. Write the description for the trigger. Say what it does and when to use it. Include the phrases a user would say.
3. Put the instructions in the order you want them done. Numbered steps work well.
4. Give it a check. End with how the agent proves the work: a command to run, a file to diff.
5. Gate anything with side effects. Add disable-model-invocation: true to deploy, commit and send skills so you stay in control of timing.

A starter you can paste:

---
name: release-notes
description: Drafts release notes from merged pull requests. Use when the user asks for a changelog or release notes.
disable-model-invocation: true
allowed-tools: Bash(git log *) Read
---

1. Run `git log --merges --since="$ARGUMENTS" --oneline`.
2. Group the entries under New, Improve and Fix.
3. One sentence per entry, no ticket numbers.
4. Print the notes. Do not write any file.

Run it with /release-notes 2026-10-01. The $ARGUMENTS placeholder is replaced by what you type after the name.

Safety: skills are code in disguise

A skill is Markdown, but it can tell the agent to run scripts, and allowed-tools can pre-approve commands. Treat installing a skill the way you treat installing a package.

• Read everything, including scripts/ and any shell lines starting with ` ! ``.
• Check `allowed-tools`. A broad grant removes the permission prompt.
• Prefer pinned sources. Copy a known commit, not a moving branch.
• Watch for prompt injection in reference files fetched from the web.
• Do not store secrets in a skill folder you commit.
• Mind the license. Some public skills are source-available only.

Claude Code lets administrators distribute skills through managed settings and lock hooks to plugins, which is useful for teams that want a reviewed set.

Common problems

Skills, subagents, commands and plugins

These four are easy to confuse, and the line between them moved recently.

• Commands are now skills in Claude Code. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. See slash commands.
• Subagents are separate workers with their own context window. A skill can run in one with context: fork. See subagents.
• Plugins bundle skills, agents, hooks and MCP servers for sharing. See plugins.
• MCP servers give the agent new tools. See MCP servers.

For a sense of how they fit together in a working setup, see Claude Code workflows and Claude Code templates.

Our take

This is an editorial guide built from the documentation. We did not run each skill we mention.

Skills are the cheapest extension point an agent has. A Markdown file and a good description cost nothing to load until used, and they travel with the repo. If you only do one thing from this page, move a procedure from your CLAUDE.md into a skill and see if the agent still follows it.

The weak spot is discovery. Public skill collections are large, quality varies, and several GitHub lists carry hundreds of open issues. We would start with Anthropic's examples to learn the shape, write your own for anything specific to your team, and treat third-party skills like third-party code: read first, pin a version, and give them the least permission that works.

The .agents/skills/ path is a quiet win for people who use more than one agent. One folder, several tools. Check the current docs of each agent before you rely on it, since these paths have been changing.

Frequently asked questions

What is a Claude Code skill? A folder with a SKILL.md file. The frontmatter says when to use it and the body holds the instructions.

Where do I put a skill so Claude Code finds it? ~/.claude/skills/<name>/SKILL.md for all your projects, or .claude/skills/<name>/SKILL.md in a repository.

Do skills work outside Claude Code? Yes. Codex, Gemini CLI, Cursor and VS Code with Copilot all document how they load SKILL.md folders.

What is the difference between a skill and a slash command? Claude Code merged them. Both create a slash command, and skills add a folder for supporting files and invocation controls.

Are skills safe to install from GitHub? Treat them like code and read the files first.

*Product names are used descriptively. We are not affiliated with Anthropic, OpenAI, Google, Cursor or Microsoft.*