Claude Code skills: what they are and how to write good ones
A skill is a reusable process you install once and the agent applies whenever it fits: a directory containing a SKILL.md, dropped into .claude/skills/ in a repo (or ~/.claude/skills/ for everywhere). Where CLAUDE.md describes your repo, a skill describes a way of working — how to review code, how to debug, how to cut a release — portable across every project you touch.
The format
--- name: codebase-tour description: Use when onboarding to an unfamiliar repository or asked "how does X work here" — build a map before answering from fragments. --- # Codebase Tour Random-walking a strange repo produces confident answers about the wrong layer. The fix is a fixed reading order: entry points and build config first, then one real feature traced end to end, then generalize. ## Process 1. Read the build/config files before any source file …
Two parts matter most: the description — it starts with "Use when …" because that's literally how the agent decides to invoke it — and the body, which the agent follows as instructions once triggered.
What separates a good skill from a wall of text
- An ordered process, not principles. "Write tests first" changes nothing. "1. Write the failing test. 2. Run it and confirm it fails on the assertion. 3. …" changes behavior, because each step is checkable.
- Real commands. A CI-triage skill that says
gh run view --log-failedgets used; one that says "examine the logs" gets paraphrased away. - Red-flag tables. The most valuable part of a mature skill is a list of the rationalizations that mean the process is being skipped ("it's probably flaky — rerun it") paired with the correction. Agents rationalize exactly like people; naming the excuse in advance defuses it.
- One job per skill. A skill that covers reviewing and refactoring and testing triggers for none of them. Narrow descriptions trigger reliably.
- Short. 60–110 lines. The skill loads into working context — pay for every line with changed behavior.
Try a complete example, free
The codebase-tour skill is a full production example (MIT): a disciplined process for onboarding to an unfamiliar repo — entry points first, one feature traced end to end, then a structured tour document. Install it:
mkdir -p .claude/skills git clone https://github.com/cyberpatrolunit/agentready cp -r agentready/skills/codebase-tour .claude/skills/
Then ask Claude Code for a tour of your codebase and watch it follow the process.