Defining Custom Skills for Claude Code: Packaging Team Abilities

1. What a skill technically is

At its core, a skill is a packaged collection of instructions that Claude Code loads for a specific recurring task as soon as the context of a request matches it. Unlike a single prompt phrasing that only applies to one session, a skill exists as a file in the project or globally in the user directory, making it permanently and equally available to every team member, provided the directory is shared.

Technically, a skill consists of a descriptive file with metadata, typically a name and a description, plus the actual instruction text that gets loaded into context on activation. Additional files can live in the same directory, say example snippets, checklists, or reference documents, which the skill pulls in only when actually needed, instead of bundling everything into one bloated file.

2. Distinction from slash commands

A slash command is invoked explicitly by the user, say by typing a command like /deploy, and runs a fixed, predefined action. The user consciously decides when this command is executed, and the flow is generally deterministic and shows little variation between calls.

A skill, by contrast, is usually not invoked explicitly but automatically recognized and loaded based on its description whenever a request matches its content. That makes skills better suited to knowledge and procedures that become relevant situationally, while slash commands remain the better choice for clearly scoped, repeatedly identical actions a user wants to trigger deliberately.

3. Distinction from subagents

A subagent is an independent execution unit with its own context window, its own tool permissions, and often its own specialized system prompt, launched for a scoped subtask and returning its result to the calling session afterward. Subagents suit tasks that consume a lot of context of their own and should therefore not burden the main context, say an extensive codebase investigation.

A skill, in contrast, runs within the same session and the same context window as the main conversation, merely adding extra knowledge or an extra procedure without spinning up its own isolated execution environment. Where a subagent solves a task independently, a skill hands the main model the tools to solve the task itself, better.

4. Structure of a skill directory

A skill lives in its own directory containing a central file with a structured header for metadata followed by the actual instruction text. That header typically defines a unique name and a precise description of when the skill should apply, because that description alone determines whether Claude Code even finds and loads the skill in a matching situation.

Additional files in the same directory, say a reference checklist or an example script, are not automatically loaded in full but pulled in only when actually needed. That keeps the base context lean while still allowing extensive detail knowledge to be kept on hand, without burdening every session with it from the start.

# Typical directory structure of a team skill
.claude/skills/code-review-checklist/
├── SKILL.md               # Metadata + core instructions
├── checklist.md            # Detailed review points, loaded only on demand
└── examples/
    └── security-issue.md   # Example finding with reasoning

5. When a custom skill pays off

A custom skill pays off as soon as a specific procedure is needed regularly on a team and cannot be exhaustively described in a few sentences, say a multi-step code review checklist, a project-specific convention for database migrations, or a recurring debugging procedure for a specific class of bugs. For one-off or very simple instructions, the effort of a dedicated skill rarely pays off, a direct prompt is perfectly sufficient there.

A good criterion is frequency: if a particular instruction gets rephrased several times a week on the team, that is a strong signal that a skill would improve consistency and save time. If an instruction is only ever needed once, a simple, directly phrased prompt remains the more efficient choice.

6. Practical example: a team skill for a code review checklist

A realistic team example is a skill that enforces a standardized code review checklist: checking for missing tests, unsafe database queries, missing PHPDoc blocks, and violations of project-specific conventions. Instead of re-explaining this checklist on every review, Claude Code loads the skill automatically as soon as a request is recognizable as a code review, and applies the criteria consistently.

The advantage over a plain CLAUDE.md rule lies in the targeted activation: the checklist only burdens context when a review is actually pending, not on every arbitrary request in the project. That keeps everyday tasks lean while still making sure nothing important gets forgotten during a review.

---
name: code-review-checklist
description: >
  Used when a code review is requested or a pull request needs
  to be evaluated. Checks for missing tests, unsafe database
  queries, missing PHPDoc blocks, and violations of the
  conventions defined for this project.
---

# Code Review Checklist

For every requested review, check the following systematically:

1. Do new public methods have unit tests?
2. Are database queries executed exclusively through
   repositories, never with raw SQL in the controller?
3. Does every new class and method have a complete PHPDoc block?
4. Are service contracts injected instead of concrete classes?

7. How skills are activated and triggered

Activation of a skill is based on matching the description in its header against the content of the current request. A description phrased too generally causes the skill to either get loaded far too often, needlessly consuming context, or, the reverse, fail to trigger in situations where it would actually be needed, because the phrasing sits too far from the actual user request.

A precise, concrete description with typical trigger words and situations noticeably improves the hit rate. It pays off to adjust the description after the team's first practical experience, once it becomes clear the skill fails to load automatically in certain expected situations.

8. Team distribution and versioning of skills

A skill only reaches its full value once it is version-controlled in the project repository and thereby automatically available to the whole team, instead of existing only locally for a single person. Through normal version control, changes to a skill can be traced, discussed in code review, and reverted if needed, exactly like any other project-relevant configuration file.

For cross-team abilities that apply beyond a single project, say general coding standards, a skill can additionally be stored globally in the user directory. A clear separation makes sense: project-specific skills in the repository, general, cross-project skills globally, so nothing gets mixed up and every skill is maintained in the right place.

9. Best practices and common pitfalls

The most common mistake when starting out is an overly extensive, monolithic skill file trying to cover everything at once, which quickly becomes unmanageable. It is better to create several small, clearly scoped skills with precise descriptions instead of overloading a single skill with every team convention. Extra material belongs in separate files loaded only on demand, not in the main file.

Another common pitfall is lack of upkeep: a skill created once and never updated afterward goes stale over time just like any other documentation. Skills should therefore go through the same review and maintenance cycle as the rest of the project code, ideally with clear ownership on the team for who makes changes to which skill.

10. Summary

11. FAQ: Defining Custom Skills: The Essentials