Skills: Packaging Reusable Expertise

What is a skill?

A skill is a packaged workflow or set of capabilities that Claude Code can call or use. Unlike a slash command (which you invoke explicitly) or an MCP tool (which Claude Code discovers automatically), a skill is a named, reusable piece of expertise.

Think of skills as libraries for agents. A library of debugging techniques, a library of deployment patterns, a library of testing strategies. When Claude Code encounters a situation (a failing test, a deployment, a code review), it can invoke the relevant skill.

Skills can be:

• Built-in — Claude Code ships with bundled skills such as /doctor, /code-review, /batch, /debug, /loop, /claude-api, and /verify, as of July 2026.
• Custom — You define skills specific to your team or project.

The main difference from slash commands is automation: a skill can be called by Claude Code automatically (if conditions match) or by you explicitly. A slash command is only invoked when you explicitly type it.

Built-in skills

Claude Code bundles a set of skills that are available in every session without any setup. Two of the most relevant to day-to-day code quality:

/verify — Builds and runs your app to confirm that a code change actually does what it should, rather than relying only on unit tests or type checks. /verify (together with /run and /run-skill-generator) infers how to launch your project from your README, package.json, or Makefile; for projects with non-standard launch steps (a database, an env file, a multi-step build), /run-skill-generator records a per-project recipe once so future runs don't have to rediscover it.

/code-review — Reviews the current diff for correctness bugs and cleanup opportunities. Pass --fix to apply findings directly, or --comment to post them as inline pull-request comments.

Since v2.1.215, both /verify and /code-review run only when you explicitly invoke them — before that version, Claude could also decide to run them on its own when it judged them relevant, which meant longer-running checks could fire without warning. Other bundled skills, like /debug (troubleshooting a session using its own debug log) and /doctor (a setup checkup that also stays available even when bundled skills are disabled), serve different day-to-day purposes and aren't part of this correctness-checking pair.

Custom skills

You can define custom skills for your team's specific workflows. A custom skill might be:

Deploy skill — Encodes your deployment process: run tests, build artifacts, run security scans, ask for approval, deploy, monitor logs.

Debugging skill — Encodes your debugging workflow: identify the problem, add logging, reproduce it, isolate the root cause, fix it, verify the fix.

Documentation skill — Encodes how to document code: analyze code, generate API docs, write usage examples, update READMEs.

Performance optimization skill — Encodes how to profile and optimize: profile the code, identify hotspots, optimize, re-profile, verify improvements.

Each skill is a named workflow that Claude Code can invoke when appropriate.

Defining a custom skill

A skill definition includes:

• Name — The identifier for the skill
• Description — When and why Claude Code should use this skill
• Preconditions — What state must be true for the skill to run (e.g., "there is a failing test")
• Steps — The actual workflow (shell commands, Claude Code operations, subagent delegations)
• Output — What the skill produces (success/failure, report, artifacts)

A simple debugging skill might be:

name: debug-failing-test
description: "Debug a test that is failing. Run the test in isolation, capture detailed output, and suggest fixes."
preconditions:
  - "A test is failing"
steps:
  1. Run the failing test with verbose output
  2. Analyze the stack trace
  3. Add debugging output to the code
  4. Run the test again
  5. Observe the output and identify the issue
  6. Propose a fix
output: "A fix for the failing test, or a detailed report of the problem if no simple fix is available"

Claude Code can then call this skill when it encounters a failing test: invoke(debug-failing-test).

Skills vs. subagents vs. slash commands: when to use each

Use a slash command for simple, deterministic workflows ("run the test suite exactly as configured").

Use a skill when the workflow is adaptive and could be reused across projects ("debug a failing test" -- the debugging approach adapts based on what the test error is).

Use a subagent when you need to delegate work to a specialized agent with its own tool set and context ("test this module" -- the subagent focuses on testing, not refactoring).

Packaging and sharing skills

Skills are most powerful when packaged and shared. A team skill for debugging becomes available to everyone. An organization skill for deploying microservices can be shared across projects.

Skills can be:

• Local — Defined in your project's configuration, used by your team
• Published — Shared on a community registry or internal package manager
• Vendored — Pulled into your project from an external source

As the Claude Code ecosystem grows, a library of reusable skills will emerge, similar to how npm packages work for JavaScript or PyPI packages for Python.

Common mistake

Conflating skills with slash commands. A slash command is for deterministic, fixed-sequence workflows. A skill is for adaptive, reusable expertise. If you're designing a custom command that always runs the same steps, use a slash command. If you're designing something that reasons about a situation and adapts, package it as a skill.