Claude Code Skills — Reusable Capability Packs

What a Claude Code skill is

A skill is a self-contained capability extension for the Claude Code CLI. It tells the model what the capability does, when to use it, and what actions are available to carry it out. The model reads the skill description during session startup and can invoke its tools during the conversation, the same way it uses built-in tools like file read or shell execute.

The key difference from a plain prompt is persistence and structure. A prompt lives in your head or in a notes file; a skill lives in the repository, has a defined interface, and travels with the code. When a new engineer joins the team and clones the repository, they get the same skills the rest of the team uses. When a skill is updated — say, the release checklist gains a new step — everyone picks up the change on their next pull.

Skills are also inspectable. Because the manifest is a plain JSON file checked in alongside the source, it is reviewable in a pull request, auditable in a compliance check, and testable like any other configuration artifact. That property matters more than it first appears for teams operating in regulated environments where the exact sequence of AI-assisted actions needs to be traceable.

How skills are structured

The two required files are the description document and the tool manifest. A third file, a schema, is optional but recommended for skills that accept structured input from the user.

The description document is a markdown file. Its first section is a short explanation of what the skill does; subsequent sections can include usage examples, prerequisite checks, and notes on edge cases. The model reads this document when it decides whether to invoke the skill and how to use it, so clarity here pays off directly in invocation accuracy. Keep the description specific: a skill that claims to handle "all release tasks" will be invoked in situations where it does not apply; a skill that describes exactly which steps it performs and under what conditions will be invoked precisely.

The tool manifest is a JSON file that declares the tools the skill exposes. Each tool has a name, a description, an input schema, and an implementation — which is typically a shell command the CLI runs when the model calls that tool. A minimal manifest for a changelog-generation skill might declare two tools: one that reads the git log since the last tag, and one that writes the formatted output to CHANGELOG.md. The model calls them in sequence; the CLI executes the shell commands; the results flow back into the session.

Authoring your first skill

Start with a workflow you already run manually and know well. The authoring process is essentially transcription: write down what you do, in the order you do it, and then translate each step into a tool declaration. The description document is the narrative version; the manifest is the structured version. If the two are consistent, the skill will work. If they diverge — the description says the skill sends a Slack notification but the manifest has no tool for that — the model will attempt to describe the gap rather than silently failing, which is a useful early signal during development.

Skill directories conventionally live under .claude/skills/ in the project root, though the path is configurable. Each skill occupies its own subdirectory with the description and manifest files inside. The CLI discovers skills automatically when it starts a session in a repository that contains the skills directory, so there is no registration step beyond placing the files in the right location.

Testing a new skill is as simple as starting a Claude Code session and asking it to perform the workflow the skill covers. Watch whether it invokes the skill's tools or falls back to ad-hoc steps; if it falls back, the description probably needs to be more specific about the trigger condition. Research on specification quality in agentic AI systems — including work published through Stanford HAI — consistently finds that ambiguous capability descriptions are the leading cause of incorrect tool selection. Be concrete.

Skill types and examples

The table below shows common skill categories, their typical use in a development workflow, and a concrete example for each.

Skill type	Typical use	Example
Release automation	Automate version bumping, changelog writing, and tag creation	A skill that reads git log, drafts CHANGELOG.md, and proposes a semver bump
Code review helper	Run pre-review checks before opening a pull request	A skill that lints, runs tests, checks for debug statements, and summarises findings
Migration runner	Apply database or config migrations safely with validation steps	A skill that checks for pending migrations, applies them, and verifies the schema diff
Incident playbook	Walk through a defined incident response sequence	A skill that collects logs, checks service health endpoints, and drafts a status update
Onboarding guide	Walk a new engineer through project setup checks	A skill that verifies dependencies, checks env vars, and confirms test suite passes

Sharing skills across a team

Because skills live in the repository, sharing them is a pull request. The team reviews the skill definition the same way they would review application code: is the tool manifest accurate? Does the description match what the tools actually do? Are there edge cases the implementation does not handle?

For organisations that want a cross-repository skills registry — a single source of truth that every project can pull from — the enterprise configuration supports a shared registry path that the CLI checks before the project-local directory. Engineers can still author project-specific skills locally; the shared registry provides the vetted baseline. See the enterprise reference for how that registry is administered and how skill invocations are logged.