Most of Claude Code's tools work because you told it to use them — you typed /deploy, or you asked it to search the web. Skills flip that. A skill sits quietly until Claude decides, on its own, that your prompt matches it. No slash, no explicit call. That's the entire design point, and it's also the thing most people misunderstand the first time they try to build one.
If you've ever installed a slash command and forgotten it existed, or wondered why some agent workflows just seem to fire at the right moment without anyone typing a command, that's skills doing their job.
What a Skill Actually Is
Strip away the framing and a skill is boring on purpose: a directory containing one file, SKILL.md, plus optionally some bundled scripts or reference material. SKILL.md itself has two parts — a short YAML frontmatter block with a name and a description, and a markdown body underneath with the actual instructions Claude follows once the skill fires.
That's the whole format. No manifest schema to fight, no plugin API to implement. The simplicity is deliberate: a skill should be as easy to write as a README, because in practice that's what it is — a README that Claude reads at the right moment instead of a human reading it once and forgetting it.
Model-Invoked, Not Typed
Here's the distinction that actually matters: slash commands are user-invoked. You type /commit, Claude runs the commit skill. Skills are model-invoked by default — Claude reads your prompt, checks it against every installed skill's description, and decides for itself whether one applies. You never type anything skill-specific. You just ask for what you want, and if a skill matches, it loads.
This is why the description field carries so much weight. It isn't documentation for a human skimming a catalog — it's the trigger condition Claude evaluates on every single turn. A vague description ("helps with formatting") matches nothing reliably. A precise one ("use when the user wants to rebind keyboard shortcuts or modify keybindings.json") matches exactly when it should and stays silent otherwise.
Some skills also expose a user-invocable form — a slash-command shorthand like /commit that expands into the same full prompt the model-invoked path would have loaded. That gives you both entry points on one skill: explicit when you want certainty, automatic when you don't want to remember the name.
Progressive Disclosure Keeps Context Cheap
Installing twenty skills doesn't mean twenty skills' worth of tokens sitting in context on every turn. Claude Code only loads a skill's short description into the standing context — enough to evaluate the trigger condition. The full SKILL.md body, typically under a few thousand tokens, only loads when the skill actually fires. Any bundled scripts or reference files inside the skill's directory load later still, and only if the task genuinely needs them.
That three-tier loading — description always resident, body loaded on match, resources loaded on demand — is what makes a large skill library viable instead of a context-budget liability. You can have dozens of narrow, specific skills installed without any of them costing anything until the moment they're relevant.
Skills vs. Slash Commands vs. Subagents
These three get confused constantly because they all package up reusable behavior, but they solve different problems:
- Slash commands are explicit macros. You type the trigger, it runs. No ambiguity, no model judgment involved.
- Skills are conditional instructions. Claude decides whether to load them based on matching your prompt against a description. Best for behavior you want available without having to remember to invoke it.
- Subagents are separate context windows with their own tool access, spun up to do a scoped task and report back — useful for parallelizing work or protecting the main conversation from a flood of intermediate search results.
The practical rule: if you always want the same exact thing to happen, use a slash command. If you want Claude to recognize a pattern and apply the right instructions without you having to name them, use a skill. If you need isolated, delegated work with its own tool budget, reach for a subagent.
Building Your Own Skill
The mechanics are close to writing a good commit message: be specific, be brief, and put the trigger condition where the model will actually read it.
- Name it precisely. The
namefield should be unambiguous — something you'd recognize six months later without re-reading the body. - Write the description as a trigger, not a summary. Include the situations where it should fire ("use when the user wants to rebind keys") and, if useful, when it shouldn't. Concrete examples in the description beat abstract phrasing.
- Keep the body focused on one job. A skill that tries to handle five loosely related tasks ends up with a mushy description that matches everything and nothing precisely.
- Bundle scripts, don't inline them. If the skill needs a helper script or a reference file, put it in the skill's directory rather than pasting it into the markdown body — that's what keeps the resident description small and the heavy content loaded only on demand.
Where Skills Fall Apart
The failure mode is almost always the description. Too broad, and the skill fires on prompts it shouldn't touch, injecting irrelevant instructions into context. Too narrow, and it silently never fires at all, so you end up doing by hand exactly the thing the skill was supposed to automate. There's no cron-job-style manual check here — if the description is wrong, the only signal you get is the skill quietly not doing its job. Test a new skill against a handful of prompts that should and shouldn't trigger it before trusting it in real work.
The Takeaway
Skills exist to close the gap between "I have to remember to invoke this" and "this just happens when it should." A SKILL.md file with a sharp description and a focused body gets you there; a vague one gets you either noise or silence. Write the description like it's the only part of the skill Claude will ever really read on a normal turn — because for most turns, it is.