What are Claude skills? (reusable instructions your agent loads on demand)

What it actually is

A skill is a folder containing one required file, SKILL.md, plain instructions Claude reads and follows, plus, optionally, extra files sitting alongside it: a script it can run, a template it can fill in, a reference doc it only opens if it needs the detail. Think of it like a recipe card filed in a specific kitchen drawer. The cook doesn’t read every recipe in the house before starting dinner. They pull the one card that matches tonight’s meal, follow it, and the rest of the drawer costs nothing until it’s needed.

You write the card in two parts: a short block at the top describing what the skill does and when to use it, and the actual step-by-step instructions below. Claude keeps that short description in view at all times, across every skill you have, and when your request matches one, it pulls in the full instructions. You can also skip the matching entirely and trigger a skill by hand, by typing /skill-name.

Why your AI just did this

If Claude just followed a noticeably more specific checklist than usual, maybe your commits are suddenly formatted a particular way, or it ran through a deploy in a fixed order, it matched your request against a skill someone wrote in advance (you, a teammate, or a plugin you installed) and loaded its instructions. There’s no hidden memory at play here, only a file getting read the same way Claude reads any other file in your project.

The reason skills exist rather than just piling everything into CLAUDE.md is cost. CLAUDE.md loads into every single conversation whether it’s relevant or not, so a long project gets slow and expensive to keep in context. A skill’s body only loads when it’s actually used. That lets you keep dozens of detailed, specialized procedures on hand, for deploying, for reviewing a diff, for a checklist you keep re-explaining, without any of them weighing on a conversation that doesn’t need them.

When you’ll run into it

• Claude names a skill it’s using, or you type / and see options that weren’t there before you or a plugin added them.
• You install a plugin (skill-creator, code-review, and similar) and new slash commands show up automatically.
• The exact same kind of request behaves differently once a matching skill exists, asking to “deploy” runs a fixed checklist instead of Claude improvising, the moment a deploy skill is written.
• You ask “what skills are available?” to see everything Claude currently has access to in this project or on your machine.
• A skill you wrote doesn’t fire on the request it was built for, and the fix is almost never the instructions, it’s the description not matching your actual phrasing.

What to check

• The skill lives in .claude/skills/<name>/SKILL.md for a project-only skill, or ~/.claude/skills/<name>/SKILL.md for one available across every project on your machine
• The description field uses the words you’d naturally type, not formal jargon, since that field alone is what Claude matches your request against
• A skill you only ever want to trigger yourself, never automatically, has disable-model-invocation: true in its frontmatter
• If a skill won’t trigger, invoke it directly with /skill-name first, to confirm the instructions themselves work before you debug the description
• Project skills committed to .claude/skills/ travel with the repo for teammates; personal skills in ~/.claude/skills/ stay local to your machine only

Say it like a dev

Instead of: “teach the AI this so it remembers forever” Say: “write this as a skill so it loads whenever it’s relevant”

Instead of: “why did it ignore my shortcut” Say: “check whether the skill’s description matches what I typed, or invoke it directly with /skill-name”

Instead of: “build a mini-AI to handle this part on its own” Say: “do we want a subagent here, running in its own context, or is a skill enough since it’s just instructions for the main agent to follow”