Claude Code skills: what they are, how to install them, which to try
A Claude Code skill is a folder with a SKILL.md file in it. The file has two parts: a description that tells Claude when to use the skill, and the instructions Claude follows when it does. Claude loads a skill by itself when your request matches the description, or you run it by typing a slash and its name. Save one in ~/.claude/skills/ to use it in every project, or in your repository’s .claude/skills/ to share it with your team. Ready-made skills install as plugins with /plugin. Use skills for work that needs judgment. If a rule has to hold every time, use a hook.
- What a skill is
- Where skills live
- Make your first skill
- Install a ready-made skill
- Run a skill
- Skills worth trying
- Skill, hook, MCP, plugin or mod?
- What skills cost in context
- When a skill doesn’t trigger
- Skills in Codex
- Questions
What a skill is
A skill is a Markdown file with YAML frontmatter at the top. The frontmatter’s description says what the skill does and when to use it. The body below it holds the instructions. The folder can also hold scripts, templates and reference files that the instructions point to.
At the start of a session Claude sees only the names and descriptions of your skills. A skill’s body loads only when the skill is used, so a long checklist or a reference document costs almost nothing until you need it. That’s the difference from CLAUDE.md, which loads in full every session. The docs suggest making a skill when you keep pasting the same instructions into the chat, or when a section of CLAUDE.md has grown from a fact into a procedure.
Older tutorials get two things wrong:
- Custom commands are skills now. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth give you/deploy. Old command files keep working. Skills also get a folder for supporting files, and Claude can load them by itself. - Skills are an open standard. Claude Code follows the Agent Skills standard, so the same
SKILL.mdworks in Codex and other agents. Claude Code adds extras of its own, such as running a skill in a subagent.
Prefer a minute of video? You’re using Claude Code wrong: skills.
Where skills live
Where you save a skill decides who gets it:
| Where | Path | Who gets it |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | You, in every project on this machine |
| Project | .claude/skills/<name>/SKILL.md | Everyone in the repository, once you commit it |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| claude.ai account | Skills you turn on in claude.ai settings | Cloud and Cowork sessions, and terminal sessions signed in with that account |
| Enterprise | The managed settings directory | Everyone on the machines where your organization deploys it |
- Same name in two places: enterprise wins over personal, and personal wins over project. Plugin skills never clash with these, because of their prefix.
- Cloud sessions don’t see your Mac’s skills. They don’t read
~/.claude/skills/. Commit the skill to the repository, or turn it on for your claude.ai account. Scheduled tasks in Claude Desktop run on your machine, so they do see personal skills. - Monorepos: Claude Code also loads
.claude/skills/from parent folders up to the repository root. A subfolder’s skills load once Claude works on files in that subfolder. - No restart needed: Claude Code picks up new and edited skills during the session. The exception is a top-level skills folder that didn’t exist when the session started: run
/reload-skillsfor that.
Make your first skill
The quickest way is to ask Claude Code: “turn the release-notes steps we just did into a skill”. Anthropic’s skill-creator (below) does the same with more care. By hand it takes two minutes. This skill writes release notes from your recent commits:
mkdir -p ~/.claude/skills/release-notes~/.claude/skills/release-notes/SKILL.md
---
description: Writes release notes from recent commits. Use when the user asks for release notes, a changelog entry or what shipped.
---
## Recent commits
!`git log --oneline --no-merges -30`
## Instructions
Group the commits above into Added, Changed and Fixed. One line each,
in words a user would understand. Skip version bumps and internal changes.The line that starts with ! runs before Claude reads the skill, so Claude works from your real commits instead of guessing. Open a git project, start claude, and either ask “what shipped this week?” or type /release-notes. The folder’s name becomes the command.
The frontmatter fields worth knowing (all of them):
descriptionis the only recommended field. Start with the main use case and the words people actually say. In the list Claude sees, the description andwhen_to_usetogether are cut at 1,536 characters.disable-model-invocation: truemeans only you can run it, with/name. Use it for anything with side effects, such as a deploy.allowed-toolslists tools Claude can use without asking during that turn, for exampleBash(git log *).context: forkruns the skill in a subagent, so its work doesn’t fill your conversation.pathstakes glob patterns: Claude loads the skill by itself only when it works with matching files.
Keep the body short. Once a skill loads, it stays in the conversation, and every line costs tokens on every later turn.
Install a ready-made skill
There are three ways. The first one gives you the most to check before you install:
- From Anthropic’s official marketplace. Claude Code adds it the first time you start an interactive session:
In a session, this command opens the plugin’s details instead of installing straight away. The details list what the plugin adds: skills, hooks, agents and MCP servers. For official plugins they also show an estimate of the context cost. Then you pick a scope: you in every project, everyone in this repository, or you in this repository only./plugin install frontend-design@claude-plugins-official/pluginwith nothing after it opens a list to browse. - From another marketplace. Add the marketplace first. Anthropic keeps its example skills, including the ones behind Claude’s document features, in the anthropics/skills repository:
/plugin marketplace add anthropics/skills /plugin install document-skills@anthropic-agent-skills - As a plain folder. Copy the skill’s folder into
~/.claude/skills/or.claude/skills/. The third-party skills command from Vercel copies it for you and knows where dozens of agents keep their skills. machine-skill (below) installs this way:npx skills add AirsupHQ/machine-skill -g -a claude-code
To check that it worked, type / and look for the skill, or run /skills. Plugin skills show up as /plugin-name:skill-name.
Before you install, remember what you’re adding. A skill brings its instructions and whatever scripts it carries, and a plugin can also run hooks and MCP servers. Read what it adds, especially from a marketplace you don’t know. One detail from the docs: a project skill’s allowed-tools applies even in a folder you haven’t marked as trusted. So before you run Claude Code in a repository you’ve just cloned, check the skills committed to it.
Run a skill
- Let Claude pick it. Ask in words that match the description.
- Run it yourself. Type
/nameat the start of your message, with anything else after it:/release-notes since v1.2. For a plugin skill, type/plugin-name:skill-name. - In the middle of a sentence,
/namedoesn’t run the skill straight away. It gives Claude permission to use it, and Claude decides from your wording whether you asked for it.
From our own tests: on a short prompt Claude doesn’t always load a skill by itself. We tested frontend-design with Sonnet 5.5 and a one-line prompt for a landing page, and Claude ignored the skill until we typed /frontend-design:frontend-design at the start. If you need a skill to run, call it by name.
Skills worth trying
Start with the ones already built in. Then add one at a time, and keep only the ones you actually use, because every skill Claude can pick by itself adds its description to every request.
- Built in, nothing to install.
/code-reviewand/debug./runand/verifylaunch your app and check a change against the running app, not only against tests./doctorchecks your setup, including unused skills, MCP servers and plugins weighed against their context cost./claude-apihelps with code that calls the Claude API.
- frontend-design (Anthropic, official marketplace) gives Claude its own choice of type and color for web pages, instead of the defaults every AI-made page shares. We ran the same short prompt with and without it. Without it we got a cream background, a serif headline and terracotta buttons. With it the page got its own font and palette. The before and after.
- skill-creator (Anthropic, official marketplace) creates skills, improves them and tests how well they work. Ask it to turn a prompt you keep pasting into a skill.
- commit-commands (Anthropic, official marketplace) adds commands for committing, pushing and opening a pull request.
- document-skills (Anthropic, anthropics/skills) adds the pdf, docx, pptx and xlsx skills that Claude’s own document features use. They’re source-available, not open source.
- machine-skill (Airsup, MIT, community): you describe a machine in one line, and Claude builds an interactive 3D model of it in one HTML file, with the physics computed. In our tests a watch movement took 23 minutes, and a full chronograph took 32 minutes and 169 parts. How it looks.
Skill, hook, MCP, plugin or mod?
The five are easy to mix up. They do different jobs:
| What it is | When it runs | Pick it when | |
|---|---|---|---|
| Skill | Instructions Claude reads and follows | You type /name, or Claude matches the description | The work needs judgment: a checklist, a playbook, reference material |
| Hook | Your command, HTTP request or prompt, set in settings | Every time its event fires, without Claude deciding | It must happen the same way every time: format after edits, block a dangerous command |
| MCP server | A connection to an outside service, with its tools | When Claude calls one of its tools | Claude needs data or actions from another system: a database, Slack, a browser |
| Plugin | A package of skills, hooks, agents and MCP servers | Once installed and enabled | A second project needs the same setup, or you want to share yours |
| Mod | A plugin whose code runs inside Claude Code | On events: a tool call, a prompt, drawing the screen | You want a pane, a button or a new behavior in Claude Code itself |
One mistake to avoid: “never touch .env” written in a skill is a request, not a guarantee. If a rule must hold every time, make it a hook that blocks the edit. A skill can carry hooks of its own in its frontmatter, and they stay on from the moment the skill runs until the session ends.
What skills cost in context
- Descriptions go into every request. Every skill Claude can pick by itself sends its name and description with every request. The full text loads only when the skill is used.
- The list has a budget of 1% of the model’s context window. If you have many skills, Claude Code drops the descriptions of the ones you use least, and then Claude can’t match them to your requests.
- Manual-only skills are free.
disable-model-invocation: truekeeps the description out of Claude’s context. Use it for skills you only ever run by hand. - A used skill stays. Its text remains in the conversation. After auto-compaction, Claude Code re-attaches the first 5,000 tokens of each skill you used recently, up to 25,000 tokens in all. Put the instructions that matter most at the top. How compaction works.
- To see the cost, run
/doctorfor an estimate and the biggest contributors, or look at the Skills row in/context.
When a skill doesn’t trigger
- The description doesn’t use your words. Rewrite it with the main use case first, in the words you’d type.
- It isn’t loaded. Check
/skillsor the/menu, then run it by name. - The YAML is broken. Claude Code still loads the body but without the description, so
/nameworks and Claude never picks it by itself.claude --debugshows the error, andclaude plugin validate ~/.claude/skillsfinds the broken files. - It has
pathsand the files are outside Claude’s working folder, for example in another worktree. Start Claude Code in that folder. - It triggers too often. Make the description narrower, or add
disable-model-invocation: true. - Claude stops following it later in the session. After compaction only the start of the skill may be left, so run it again. A step Claude skips every time belongs in a hook.
Skills in Codex
Codex reads the same SKILL.md format, from different folders. Your personal skills go in ~/.agents/skills/. A repository’s skills go in .agents/skills/, and Codex looks for them in every folder from where you started up to the repository root. You call a skill with $ or /skills, and Codex also picks one by its description. It ships with skill-creator and skill-installer. A skill that needs only name and description works in both agents. Claude Code’s extras, such as ! commands and context: fork, are its own, so don’t count on them in Codex.
Where Meowdoro fits
We build Meowdoro, a focus timer around the MacBook notch, and it’s a small example of the plugin side of this guide. When you click Connect in its settings, it installs a small plugin into Claude Code and Codex. The plugin’s hooks tell the notch when a session finishes or is waiting for you. We used hooks, not a skill, because this has to happen every time. So while a skill works for ten minutes, you can step away: the notch tells you when Claude needs you, and your break stays a break (how it shows agents). Try it and tell us what’s missing.
Questions
What is a skill in Claude Code?
A folder with a SKILL.md file: a description of when to use it, and instructions Claude follows. Claude loads it when your request matches the description, or you run it with /name.
Where are Claude Code skills stored?
Personal skills are in ~/.claude/skills/, project skills in .claude/skills/ in the repository, and plugin skills inside the plugin. Run /skills to see what’s loaded.
How do I install a skill in Claude Code?
For a plugin, run /plugin install name@marketplace, for example /plugin install frontend-design@claude-plugins-official. For a plain skill, copy its folder into ~/.claude/skills/.
Are skills the same as slash commands?
Custom slash commands were merged into skills. A command file and a skill with the same name both create the same /name, and skills add supporting files and automatic loading.
What’s the difference between a skill and a hook?
A skill is instructions Claude interprets, so the result can vary. A hook is your own command that runs every time its event fires, without Claude deciding. Guardrails belong in hooks.
What’s the difference between a skill and an MCP server?
An MCP server connects Claude to an outside system and gives it tools. A skill gives Claude knowledge and steps, which can include how to use those tools well. They work well together.
Do skills use tokens?
Yes. The description of every skill Claude can pick by itself goes with every request, and the full text is added once the skill is used. Skills you only run by hand can leave their descriptions out with disable-model-invocation: true.
Do Claude Code skills work in Codex?
The format is the same open standard, so a simple skill works in both. Codex reads skills from ~/.agents/skills/ and .agents/skills/ rather than .claude/skills/.
Related guides
Sources: the Claude Code documentation on skills, extending Claude Code, installing plugins and mods; OpenAI’s skills documentation for Codex; the repositories anthropics/skills, anthropics/claude-plugins-official, AirsupHQ/machine-skill and vercel-labs/skills. Read on November 5, 2026. Our tests of frontend-design and machine-skill were run on November 1–3 with Claude Code 2.1.309.