Claude Code skills: install them, write them, trust them

A Claude Code skill is a folder with a SKILL.md file in it: a few lines of YAML that say what the skill is for, then instructions written in plain Markdown. Claude reads only each skill's name and description until your request matches one, then loads the rest. You can also run a skill yourself by typing / and its name. A skill can carry scripts, templates and reference files, and it follows an open format, so the same folder works in Codex, Cursor and Gemini CLI once it sits where those tools look.

That is the whole idea. The rest of this guide is what the top search results for "Claude Code skills" leave out: where skills live in each tool, how to install one without guessing, how to write one that triggers when it should, how to test that it works, and how to check a stranger's skill before it runs on your machine. Every command and limit below comes from the tools' own documentation, linked where it's used.

I build and sell skill packs for Claude Code, Codex, Cursor and Gemini CLI, so I've installed, written and broken a lot of them. This is the guide I'd hand someone on day one.

What is a Claude Code skill?

A skill is a reusable set of instructions Claude loads when it needs them. Anthropic's own rule of thumb: make a skill when you "keep pasting the same instructions, checklist, or multi-step procedure into chat" (Claude Code docs). Unlike CLAUDE.md, which loads in every session, a skill's body loads only when it's used.

On disk, a skill is a folder named after the skill. Only SKILL.md is required; the other folders follow the conventions of the Agent Skills specification:

release-notes/
├── SKILL.md       required: frontmatter and instructions
├── scripts/       optional: code the skill runs
├── references/    optional: documents Claude reads when it needs them
└── assets/        optional: templates, images, data

And a complete, working SKILL.md:

---
name: release-notes
description: Drafts release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry, or what changed since the last release.
---

# Release notes

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the commits since it with `git log <tag>..HEAD --oneline`.
3. Group them under Added, Changed and Fixed. Leave out merge commits.
4. Show the draft. Don't write it to a file unless asked.

The frontmatter between the --- lines is how Claude finds the skill. The Markdown below it is what Claude follows once it has.

Two more things worth knowing:

• Skills replaced custom slash commands. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. A skill adds a folder for supporting files and the option for Claude to load it on its own.
• Claude Code ships with skills of its own, such as /code-review, /debug, /batch and /loop. They work like yours, and a skill you write with the same name replaces the bundled one.

How does Claude decide when to use a skill?

Skills load in three stages, which the specification calls progressive disclosure (agentskills.io):

1. Discovery. At the start of a session, Claude sees only each skill's name and description, about 100 tokens per skill.
2. Activation. When your request matches a description, Claude loads that skill's full SKILL.md.
3. Execution. Claude reads the skill's reference files or runs its scripts only as the instructions call for them. A script's code never enters the conversation; only its output does (Anthropic platform docs).

So the description does all the work of getting a skill picked. Anthropic puts it plainly: the description is "what Claude matches your request against when determining whether to trigger the Skill."

There are two ways to run a skill: Claude picks it because your request matches, or you type /release-notes. Two frontmatter fields decide who is allowed to:

• disable-model-invocation: true means only you can run it. Use it for anything with side effects, like a deploy or a message that goes out.
• user-invocable: false hides it from the / menu, so only Claude loads it. Use it for background knowledge that isn't a command.

Three limits explain most "why didn't it trigger?" questions:

• The listing has a budget. Claude Code keeps every skill's name in context, but the descriptions share a budget of 1% of the model's context window. When you have more than fits, it drops descriptions starting with the skills you use least, and a skill without its description is hard to match.
• Each description is capped at 1,536 characters, counting the optional when_to_use field. Put the key use case first.
• Compaction trims skills. When a long conversation is summarized, Claude Code re-attaches the first 5,000 tokens of each recently used skill, within 25,000 tokens for all of them. Put the steps that must be followed at the top of the file.

Where do Claude Code skills live?

Claude Code looks in several places (docs):

When two skills share a name, enterprise wins over personal, and personal wins over project. Plugin skills carry the plugin's name in front, so they never collide. Project skills load from the folder you start in and every parent folder up to the repository root, which is handy in a monorepo.

A few details catch people out:

• Cloud sessions and routines don't read ~/.claude/skills. If a skill has to work there, commit it to the repository.
• Edits are picked up mid-session for skills in folders that existed when the session started. If you create a new top-level skills folder during a session, run /reload-skills.
• Cloning a repository full of skills installs nothing. Claude Code only finds a skill whose folder sits directly in one of the paths above.

Codex, Cursor and Gemini CLI

Skills follow the open Agent Skills standard, which Anthropic started and published, so the format carries over. The folders don't:

Sources: Codex, Cursor, Gemini CLI.

One folder for every tool

Claude Code reads ~/.claude/skills. Codex, Cursor and Gemini CLI all read ~/.agents/skills. So keep one copy of each skill and link it into both:

mkdir -p ~/.claude/skills ~/.agents/skills
ln -s ~/skills/release-notes ~/.claude/skills/release-notes
ln -s ~/skills/release-notes ~/.agents/skills/release-notes

Claude Code and Codex both document support for linked skill folders. Cursor and Gemini CLI read those folders but don't say whether they follow links, so if either one misses a linked skill, copy the folder instead.

For a skill to work everywhere, write its frontmatter to the specification rather than to Claude Code:

• name: lowercase letters, numbers and hyphens, 64 characters at most, matching the folder name.
• description: 1,024 characters at most. Claude Code allows more, but the other tools don't have to.
• Optional: license, compatibility, metadata and allowed-tools.

Claude Code's extra fields, like argument-hint or context, are ignored by tools that don't know them. They're rejected outright if you upload the skill to claude.ai or the Skills API, which accept only name, description, license, compatibility, metadata and allowed-tools.

How do you install a Claude Code skill?

There are two routes: copy the folder yourself, or install a plugin from a marketplace. Whichever you choose, read the skill first (see how to vet a skill below).

From a GitHub repository

Find the folder that holds the skill's SKILL.md, and copy that folder, not the whole repository, into your personal or project skills folder:

git clone https://github.com/<owner>/<repo>.git /tmp/<repo>
cp -r /tmp/<repo>/<path-to>/<skill-name> ~/.claude/skills/

Swap ~/.claude/skills/ for .claude/skills/ inside a repository to install it for that project only. Then run /skills in Claude Code to see it listed.

From a plugin marketplace

A plugin bundles skills (and sometimes hooks, subagents and MCP servers) for installing in one step (docs). Add the marketplace, then install from it. Anthropic's own skills repository works this way (anthropics/skills):

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

Claude Code asks where to install: for you (user), for everyone on the repository (project), or for you in this repository only (local). Run /plugin on its own to browse what's available. From the shell, the same install looks like this:

claude plugin install <plugin>@<marketplace> --scope project

Anthropic's official marketplace, claude-plugins-official, is added automatically the first time you use Claude Code interactively. Plugins from official marketplaces update themselves by default; plugins from third-party marketplaces don't. Anthropic says plainly that it "doesn't review third-party marketplaces."

In Codex, Cursor and Gemini CLI

• Codex: copy the folder into .agents/skills/ or ~/.agents/skills/, or type $skill-installer followed by a skill's name to install from OpenAI's curated set. To turn a skill off without deleting it, add a [[skills.config]] entry with enabled = false to ~/.codex/config.toml and restart Codex.
• Gemini CLI: gemini skills install <git-url>, with --scope user or --scope workspace. It shows a security confirmation first; the --consent flag skips that, so leave it off.
• Cursor: copy the folder into one of its skill folders. It already loads the ones in ~/.claude/skills.

You'll also see npx skills add owner/repo in some guides. That's skills.sh, a third-party installer from Vercel, not an Anthropic tool. Treat it like any other installer that fetches code for you.

How do you write your own skill?

The fastest way to learn the format is to write one:

1. Make the folder:

   mkdir -p ~/.claude/skills/release-notes

2. Save the SKILL.md from the top of this guide into it.
3. In a repository with a tag, ask Claude "what changed since the last release?" It should load the skill on its own. Typing /release-notes runs it directly.

Most of the craft is in the description:

• Say what it does and when to use it. "Drafts release notes. Use when the user asks for release notes, a changelog entry, or what changed since the last release" beats "Release notes helper."
• Use the words people actually type. Claude matches your request against the description, so include the phrases you'd use to ask.
• Put the main use first, in case the description is cut short.
• Narrow it when it fires too often. The paths field limits automatic loading to files that match a pattern, such as *.sql for a database skill.

And for the body:

• Keep SKILL.md under 500 lines. Move detail into reference files and link each one from SKILL.md, saying when to read it, so Claude opens it only when needed.
• Point at bundled files with ${CLAUDE_SKILL_DIR}, which Claude Code replaces with the skill's own folder wherever it's installed. The same variable works in allowed-tools, so allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *) lets the skill run its own script without asking you each time.
• Put the must-follow steps at the top, because that's the part that survives compaction.

If you'd rather not start from a blank file, Anthropic's skill-creator plugin writes skills and tests them:

/plugin install skill-creator@claude-plugins-official

How do you know a skill actually works?

This is the step nearly every guide skips. Anthropic's docs put it best: "Seeing a skill trigger tells you Claude found it, not that it did what you intended."

Test two things separately: whether Claude loads the skill for the prompts it should, and whether the result is right when it does. The method from the docs is a baseline comparison:

1. Write three to five realistic prompts, worded the way you'd really ask.
2. Run each in a fresh session with the skill available. A fresh session matters, because the context left over from writing the skill hides gaps in its instructions.
3. Turn the skill off and run them again. For your own skills, set the skill to "off" in the skillOverrides setting.
4. Compare the two. If the results match, the skill isn't doing anything.

Tools that automate it:

• skill-creator runs test prompts in isolated sessions, grades the results, compares two versions of a skill, and tunes the description with prompts that should and shouldn't trigger it.
• claude plugin eval does the with-and-without comparison for skills that ship in a plugin, and exits with an error below a score you set, so it can gate a CI run.
• claude plugin validate ~/.claude/skills finds SKILL.md files whose frontmatter doesn't parse. That matters because a skill with broken YAML still loads, just with none of its fields set.

How do you vet a skill before you install it?

A skill is software. Anthropic says to "use Skills only from trusted sources" and to treat installing one "like installing software," because a malicious skill "can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose" (platform docs). Plugins go further: "A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges," and its hooks and MCP servers run outside Claude Code's sandbox (plugin security).

Before you install one, check:

1. Every file, not just SKILL.md. Read the scripts and reference files. In a plugin, also read hooks/hooks.json, .mcp.json and anything in bin/, which Claude Code adds to the command path.
2. Where it reaches out. Search the folder for network calls and hidden code, for example grep -rnE "curl|wget|base64|eval|https?://" <skill-folder>, and make sure you know why each one is there. Anthropic singles out skills that fetch from external URLs: "Even trustworthy Skills can be compromised if their external dependencies change over time."
3. What allowed-tools grants. It doesn't restrict Claude; it pre-approves the listed tools so Claude can use them without asking you. A project skill's allowed-tools applies even in a folder you've never marked as trusted, so check the skills in a cloned repository before you start Claude Code there.
4. Commands that run on load. A line starting with ! runs a shell command before Claude sees the skill. The disableSkillShellExecution setting turns those off in personal, project and plugin skills.
5. What a plugin contains, before installing: clone it and run claude --plugin-dir <plugin-folder> plugin details <plugin-name>, which lists its skills, agents, hooks and servers without starting a session.
6. That what you reviewed is what you run. When a plugin updates itself, "the files you reviewed can change on disk." Pin a marketplace to a tag with /plugin marketplace add owner/repo#v1.2.0, and leave auto-update off for third-party marketplaces.

Two myths worth dropping while you're here: allowed-tools doesn't limit what a skill can use (disallowed-tools does), and a skill is not "just Markdown" once it has a scripts/ folder.

Skills vs CLAUDE.md, subagents, hooks and MCP

Claude Code has several ways to shape what Claude does, and the features overview sets out which to use when:

Two lines from that page settle most debates. On MCP: "MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively." On hooks: "If a rule must hold every time, make it a hook." A skill is instructions Claude interprets; a hook is code that runs whether Claude remembers or not.

They also combine. A skill with context: fork in its frontmatter runs in a subagent, so a long investigation doesn't fill your main conversation.

Which skills are worth installing first?

Start with the ones whose source you can trust:

• The bundled skills. /code-review and /debug are already there. Try them before installing anything.
• Anthropic's skill-creator, from the official marketplace, if you're going to write your own.
• Anthropic's document skills (Word, Excel, PowerPoint and PDF), from the anthropics/skills marketplace shown above.
• Your own. The best skill is usually the checklist you already paste into chat every week.

For community skills, prefer a marketplace that pins versions: Anthropic's community catalog pins each plugin to a specific commit, so you get what was listed. Whatever the source, run the checks above before you install.

If you build websites for clients, our packs are paid, reviewed skills for exactly that work. Spotter Round makes the agent prove its work (layout, pixels, speed, and what the live site actually serves) instead of telling you it's done. The other packs cover multi-agent setup, HTML email, WordPress on Bricks, Cloudflare, Stripe and Supabase and campaign tracking. Each pack's page lists what its scripts touch on your machine, and the verification skill is free.

Troubleshooting Claude Code skills

It doesn't trigger. Run /skills to confirm it's listed. Check that --- is the very first line of SKILL.md, since frontmatter anywhere else isn't read. Run claude plugin validate on the folder to catch broken YAML. Then look at the description: does it contain the words you actually used? Run /doctor to see how much of the listing's budget your skills use; with many skills installed, your description may have been dropped.

It triggers when it shouldn't. Make the description more specific, limit it to matching files with paths, or set disable-model-invocation: true and run it by hand.

It stops following the steps in a long session. After compaction, only the first 5,000 tokens of a skill come back. Move the critical steps to the top, or run the skill again.

It's missing in a cloud session or a routine. Personal skills in ~/.claude/skills aren't read there. Commit the skill to the repository.

You have too many. /skill-doctor shows what each skill costs and how often you use it, so you can turn off the ones you don't.

Frequently asked questions