AI & automation · Guide
What are Claude Code skills, and how should a team use them?
A Claude Code skill is a folder with a SKILL.md file: instructions, scripts and reference material for a recurring task, such as reviewing a pull request or preparing a release. The agent reads only each skill's name and description and loads the rest when a task calls for it, or when someone types /skill-name.
Master TimmUpdated on 6 min read
What a Claude Code skill is
A skill is packaged procedural knowledge: the steps someone on the team would explain to a new colleague, written once and read by the agent whenever the task comes up. The format follows the open Agent Skills standard, which tools other than Claude Code also read.
- Frontmatter: The name and the description, which say what the skill does and when to use it; this is the part the agent sees in every session.
- Body: The instructions in Markdown, loaded when the skill is used.
- Supporting files: References, templates and scripts in the same folder, read or run only when the instructions call for them.
- Location: In ~/.claude/skills, the skill serves one person across all projects; in .claude/skills, inside the repository, it is versioned with the code and reaches the whole team.
Spec-Driven Development tools such as Spec Kit and OpenSpec now install as skills: each step of the method becomes a skill the agent calls in chat.
Progressive disclosure: why a skill barely weighs on the context
The context window is limited, and everything in it costs tokens and the model's attention. Skills load in three levels, each one only when needed.
| Level | When it enters the context | Approximate cost |
|---|---|---|
| MetadataName and description | At the start of every session, for every skill | About 100 tokens per skill |
| InstructionsThe SKILL.md body | When the task matches the description or someone types /name | Recommended under 5,000 tokens |
| ResourcesReferences, templates and scripts | Only when the instructions say to read or run them | Nothing until used; for a script, only its output |
There are two practical consequences. The description decides whether the skill fires: too vague and the agent never finds it, too broad and it loads at the wrong time. And once loaded, the skill stays in the context for the rest of the conversation, so every line of the body is a recurring cost; the documentation recommends keeping SKILL.md under 500 lines.
Skills, hooks and CLAUDE.md: what goes where
All three hold team knowledge for the agent, but they come in at different moments. Picking the wrong place wastes context or leaves an important rule without a guarantee.
| Feature | When it acts | Use it for |
|---|---|---|
| CLAUDE.md or AGENTS.mdThe project rules | In every session, in full | Conventions and commands that always apply, such as the package manager and the test command |
| SkillOn-demand knowledge or procedure | When the task matches the description, or on /name | Checklists, style guides and multi-step playbooks |
| HookA command fired by an event | Every time the event happens, such as before or after a tool runs | What must never fail: linting after every edit, blocking a dangerous command |
One rule from the Claude Code documentation settles most cases: an instruction in CLAUDE.md or in a skill is a request, not a guarantee. If something must happen every time, such as blocking edits to a .env file, it becomes a hook. And once CLAUDE.md grows past 200 lines, reference material should move into skills.
How to test and version skills
Seeing a skill fire only proves the agent found it. To know it works, measure two things separately: whether it fires on the right requests, and whether the result improves when it is active.
- Build the cases: Real requests that should fire the skill and similar requests that should not.
- Compare with and without the skill: Run each case in a fresh session, once with the skill and once with it turned off, and compare the results.
- Automate the comparison: The skill-creator plugin stores the cases in evals/evals.json and measures pass rate, time and tokens; for skills shipped in a plugin, claude plugin eval can fail CI below a minimum score.
- Version it like code: The skill lives in .claude/skills, changes through a reviewed pull request and becomes a plugin when several repositories need it.
Tests and versioning are part of how we write skills, along with clear triggers and on-demand loading.
Governance: skills on a team, safely
A skill can tell the agent to run code, so installing a skill is much like installing software. Anthropic's documentation recommends using skills only from trusted sources and auditing every file of a third-party skill before use.
- Permissions inside a skill: The allowed-tools field grants tools without approval during the turn the skill runs, even in untrusted folders; review that field on every skill that enters the repository.
- Actions with side effects: Skills that deploy, commit or send messages carry disable-model-invocation: true, so only a person can invoke them.
- Permission rules: Skill(deploy *) in a deny rule keeps the agent from using the skill without editing its file.
- Inventory: The /skill-doctor command shows the context cost and usage of each skill and helps switch off the ones nobody uses.
On the program we work on for The Hackett Group, the operating model uses 12 agents and 25 skills with quality-gate hooks, on Claude Code and OpenCode.
Related service
AI Software Automation
Coding agents on your team, with specs and quality gates.
Free first conversation · Reply within 1 business day
See also: Technical Mentoring & AI Training.
Frequently asked questions
Are skills and slash commands the same thing?
Almost: in Claude Code, custom commands have been merged into skills, and a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. A skill adds a folder for supporting files, control over who can invoke it and automatic loading when the task calls for it.
Do skills work in agents other than Claude Code?
They work in tools that adopt the open Agent Skills standard, which defines SKILL.md with a name and a description; Codex, for example, reads skills from the .agents/skills folder. Claude Code-only fields, such as context: fork and hooks, do not apply elsewhere, so a skill meant to be portable sticks to the standard's fields.
How many skills should a team have?
One for each recurring task that justifies it, and no more: every skill the agent can invoke takes space in the description listing of every session. When the listing exceeds its budget, about 1% of the context window, Claude Code drops the descriptions of the least-used skills, and the agent has a harder time matching them.
Can we install ready-made skills from the internet?
Yes, with the care you give to installing software: read every file, look for network calls and file access that do not match the skill's purpose, and be wary of skills that fetch content from external URLs. In a client repository, a third-party skill goes through the same review as any dependency.
Sources
Master Timm · Updated on