Define Skills in Claude Code Once

Recurring tasks follow fixed rules, but those rules rarely live where an AI assistant can read them. Skills in Claude Code turn implicit team knowledge into versionable artifacts.

The first session with a coding agent impresses; the twentieth wears you down. Not because the model gets worse, but because the same ground rules have to be re-explained every time: Which layer rules apply? What does a commit the team will accept look like? Which sections belong in an Architecture Decision Record? The answers live in individual people's heads, or in a prompt someone wrote three weeks ago and then lost. That shifts the problem: it's not about the model's capabilities, but about the reproducibility of how it's applied. Skills in Claude Code therefore treat working instructions for agents like code: written, versioned, distributed, revised.

The problem: prompts don't scale

A good prompt is a disposable artifact. It emerges iteratively through dialogue and disappears with the chat history. This has three consequences.

Redundancy. Anyone running AI-assisted code reviews daily types out the same requirements every time: check nullable handling, flag missing tests, ignore generated migrations, sort findings by severity. Every repetition is a chance to forget something.

Variance. Ten developers write ten prompts for the same task. The results differ systematically, because the model fills every gap in the instructions with plausible default assumptions. Say nothing about error handling, and you get exceptions instead of a Result pattern. That's not a model failure — it's a specification problem.

Knowledge loss. At best, the senior developer's refined review prompt ends up in a team chat and rots there, with no change history and no place where new colleagues are bound to find it.

‍

What Skills are

A Skill is a folder containing a SKILL.md file, optionally supplemented with templates, reference documents, and executable scripts. The file contains YAML frontmatter followed by Markdown instructions. Exactly two fields are required: name and description.

---
name: adr-writer
description: Creates and updates Architecture Decision Records following
 the internal template. Use this Skill when an architecture decision
 needs to be documented or an existing ADR needs to be updated.
---

# Architecture Decision Records

## Workflow
1. Determine the next free number from `docs/adr/`.
2. Use the template from `template.md` in this Skill folder.
3. Verify affected modules from the code, don't assume.

## Rules
- No decision without two rejected alternatives.
- Status only: proposed | accepted | superseded


Nothing more is needed. The simplicity is intentional: a Skill is a text file — reviewable, diffable, and committable like any other source.

‍

Progressive Disclosure

The key mechanism is staged loading. At session start, Claude Code knows only the metadata of all Skills — name and description, a few dozen tokens per Skill. Only once a task matches the description does the agent load the full SKILL.md; referenced additional files follow even later. A team can thus provide thirty Skills without weighing down the context with thirty rulebooks.

The description thus becomes the most important field: it's not documentation for humans, but the agent's routing criterion. "Helps with documentation" almost never triggers; naming concrete trigger situations and keywords hits reliably.

A second, often overlooked point: Skills can contain scripts that the agent runs via shell. This lets you pull deterministic sub-steps out of the language model: a model shouldn't have to guess at something a grep can answer exactly.

‍

Distinguishing Skills from project instructions and slash commands

Skills don't compete with the other control mechanisms. The project instruction file CLAUDE.md stays permanently in context, which is right for a handful of universal facts like the tech stack and build commands. A slash command has to be invoked explicitly, so someone has to know it exists. A Skill, by contrast, the agent selects itself depending on the situation. Rule of thumb: what applies in every session belongs in the project instructions; what applies situationally belongs in a Skill.

‍

From prompt to distributable artifact

Personal Skills live in the user profile and follow the developer across every project. Project-level Skills live in the repository under .claude/skills/ and ship with the code. For organization-wide distribution, Claude Code uses plugins from marketplaces that are fed from a Git repository.

The organizational effect is bigger than the technical one. A committed Skill goes through pull requests, with an author, a history, and reviewers. The discussion about "how we review" happens as a comment on a specific line, not in a meeting. New team members inherit the conventions with the clone. Because the same format also works in the Claude app and via the API, a Skill stays usable across environments.

‍

Real-world examples

Standardizing code review. Starting point: twelve developers, inconsistent results — some reviews flag formatting details, others miss missing authorization checks. The Skill fixes the review order, severity logic, and output format, points to a file with security-relevant checkpoints, and includes a script that determines changed files against the target branch. Result: reviews become comparable; lessons learned from production incidents land in the Skill as a pull request and take effect for everyone from the next merge on.

Architecture documentation. Starting point: the documentation is six months out of date because piecing together module boundaries is tedious. The Skill describes how the agent derives a current-state picture: identify entry points, evaluate project references, check dependency directions against the layer rules, flag deviations as violations. Result: documentation becomes a repeatable derivation. Often the more interesting part is the side effect: the comparison uncovers creeping violations of layer separation.

Technical writing. Starting point: terminology and structure vary by author, and editing keeps correcting the same points. The Skill fixes the target audience, outline grid, required translations, and a blocklist of clichés, plus two reference texts for calibration. Result: the first draft already hits the house style; editing shifts from formalities to argumentation.

‍

Limits and challenges

Skills solve a specification problem, not a judgment problem. Where a task requires genuine trade-off weighing — say, whether a module should be split at all — no rulebook helps. Three risks matter in practice: outdated instructions are actively harmful, because they consistently produce wrong results; Skills therefore need ownership and regular review. Poorly worded descriptions lead to silent Skills: the result looks plausible but doesn't match the standard. And forty overlapping Skills create selection uncertainty instead of value.

For rollout, what works well: start with two or three daily workflows, use existing prompts as starting material, review Skills in the repository, and spot-check results against the rules.

‍

Conclusion

Skills shift the work of AI assistance from interaction to specification. The payoff lies less in saved keystrokes than in reproducibility: results become comparable, standards become verifiable, experience becomes transferable. Teams shouldn't start with a Skill library — they should start with the workflow that gets re-explained most often today: the best candidate and the cheapest test.

In the medium term, this creates a new category of repository content: alongside code, tests, and infrastructure, the machine-readable description of how the team itself works. Whoever maintains it aligns every agent that works on the codebase going forward.