Claude Code Skills: What They Are and When to Use One

Extending a coding agent used to mean one thing: writing a longer prompt. Modern agents separate that into distinct layers, each with different reliability properties, and picking the wrong one is the most common reason a team's customization does not stick.

Skills are one of those layers. This guide covers what a skill actually is, the four things it is regularly confused with, and a decision rule for which to reach for.

What a skill is

A skill is a folder of instructions, and optionally supporting files, that the agent loads on demand when the work calls for it. It turns a general-purpose agent into a specialist for your codebase, your domain, or a particular workflow.

The important word is on demand. A skill does not sit in context permanently consuming tokens. The agent sees that the skill exists and what it is for, and loads the detail when a task matches. That is what makes it practical to have many of them.

The shape is a directory with an instruction file describing what the skill does, when to use it, and the procedure to follow. Helper scripts and reference material can live alongside it and be read when needed.

Because a skill is a folder, it goes in version control. Which means the team's way of doing something is reviewed in a pull request like anything else, rather than living in individual engineers' personal configs.

The four things it gets confused with

This is the part worth getting right, because each layer solves a genuinely different problem.

Slash command. A prompt template. You type it, it expands. Use one when you repeat a request with slight variations and there is no real logic involved.

Skill. Domain knowledge plus a procedure, loaded when relevant. Use one when there is something to know: a workflow with steps, conventions specific to your codebase, helper files the agent should read.

Subagent. A separate context window doing isolated work. Use one when a task would otherwise flood the main context, or when several pieces of work can run in parallel without seeing each other.

Hook. Event-driven code that runs deterministically. Use one when a rule must hold. This is the key distinction: a skill is instruction the model interprets, a hook is code that executes. A model can be talked out of an instruction. It cannot talk its way past a hook.

MCP server. A capability the agent does not otherwise have, exposed over a protocol. Use one when the agent needs to do something new: drive a browser, query a database, run your test suite. See what is MCP?

The decision rule in one line: template it with a slash command, teach it with a skill, isolate it with a subagent, enforce it with a hook, and enable it with an MCP server.

Plugins bundle the rest

A plugin is a versioned unit that ships skills, subagents, slash commands, hooks and MCP server definitions together. It is the distribution format rather than a sixth kind of thing.

This matters for teams. Without a bundle, adopting a workflow means asking every engineer to configure five things correctly. With one, it is a single install and everyone gets the same setup at the same version.

Where skills earn their keep

Encoding a workflow that has real steps. Anything where the agent should follow a procedure rather than improvise: how your team writes migrations, how a release gets cut, what a bug report needs before it is actionable.

Codebase conventions with reasons attached. Not "use tabs," which belongs in a formatter, but the conventions that need explaining: why this module is structured the way it is, which patterns are deliberate and which are legacy.

Anything with reference material. A skill can carry files the agent reads when it needs them, which is a better home for a long reference than a prompt nobody wants to maintain.

Verification procedures. What "done" means for a change in your codebase, and how to demonstrate it. This is where we spend most of our time: Shiplight ships as an MCP server plus a set of skills, because the browser access needs a protocol and the procedure for verifying a change well is knowledge. One without the other underperforms. The agent with a browser but no procedure checks the happy path and stops.

Where a skill is the wrong tool

When the rule must hold every time. Use a hook. A skill is advisory and the model decides whether it applies.

When you need a new capability. A skill cannot give the agent a browser. It can only tell an agent that already has one how to use it well.

When the instruction is one line. Overhead without benefit. Put it in your project's instruction file.

A practical note on scope

The failure mode with skills is writing them too broadly. A skill called "development" that covers everything will either load constantly or never load usefully, because the agent cannot tell when it applies.

Narrow beats comprehensive. A skill with a clear name and a clear trigger condition gets loaded at the right moment. Several narrow skills outperform one large one, and they are easier to review.

Frequently Asked Questions

Related Reading

• What is MCP?: the layer that adds capability rather than knowledge
• Claude Code testing: skills and MCP working together on verification
• Codex vs Claude Code: how the extension models compare
• Context engineering for coding agents: the wider discipline
• Agent-first development: what changes when agents are primary authors