This site's repository has 14 skills under .claude/skills. One writes blog posts, one strips AI tells from prose, two cover tests, one ships code. They exist because I kept typing the same instructions into chat, and every time I typed them a little differently. A skill turns a procedure your team already follows into a file the agent loads when the task calls for it. Below is how I write them: what goes in the file, how to make the agent pick the right one, and when a skill is the wrong answer.
What is a Claude Code skill, and how is it different from CLAUDE.md and hooks?
A skill is a directory with a SKILL.md file inside. Project skills live in .claude/skills/<name>/SKILL.md and are committed with the repo, so the whole team gets them; personal ones live in ~/.claude/skills. The official docs put the key difference in one line: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it." (Claude Code docs, October 2026) Custom slash commands have been merged into skills, so a file in .claude/commands/deploy.md and a skill named deploy both create /deploy.
CLAUDE.md is loaded at the start of every session, and Claude treats it as "context, not enforced configuration". To block an action whatever the model decides, the memory docs point to a PreToolUse hook (Claude Code docs, October 2026). Each of the three has a different job:
| CLAUDE.md | Skill | Hook | |
|---|---|---|---|
| Loaded | Every session, in full | Description always; body only when used | Runs on a tool event |
| Good for | Facts the agent cannot infer: package manager, build quirks, delivery rules | Procedures: writing a post, TDD, shipping a change | Things that must never happen: reading secrets, force-pushing |
| Enforced? | No, it is context | No, it is context | Yes, it can deny the tool call |
| Cost | Every line, every turn | One description line per turn | Script runtime |
The docs give a test I agree with: create a skill when you keep pasting the same checklist or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.
What goes inside a SKILL.md file?
Two parts. YAML frontmatter on top, then markdown instructions. All frontmatter fields are optional, and the docs recommend only description. This is the top of the blog-post skill in this repo, the one I use to draft articles like this one:
---
name: blog-post
description: Use when writing or planning a blog post for this site (topic, outline, draft, SEO fields, or creating the Sanity draft).
---
# Blog post
Pillars, calendar, backlog and measurement: [docs/content-strategy.md](../../../docs/content-strategy.md). Pick the topic from there.The body is 122 lines: who the reader is, evidence rules, the article structure, SEO field limits, link rules, and a numbered workflow that ends with creating the post in the CMS as a draft. It reads like a brief I would give a new writer, with the difference that the agent reads all of it every time.
The fields I use most:
| Field | What it does | When I use it |
|---|---|---|
| description | Tells Claude what the skill does and when to load it | Always |
| disable-model-invocation: true | Only a human typing /name can run it | Workflows I want to start by hand: triage, retros, ticket splitting |
| user-invocable: false | Hidden from the / menu, only Claude loads it | Background knowledge nobody should call directly |
| allowed-tools | Tools usable without a permission prompt during that turn | Repetitive, low-risk commands |
| context: fork | Runs the skill in a forked subagent | Long jobs whose detail should stay out of the main session |
How do you write a skill description that Claude actually uses?
The description is the only part of a skill that sits in context all the time. Claude reads it to decide whether to load the body. So a description is a trigger list, and a vague one means the skill never fires. The docs add a hard limit: description and when_to_use together are truncated at 1,536 characters in the skill listing, so the key use case goes first.
This is the description of the tdd skill in this repo:
description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.It opens with the name of the thing, then lists the distinct situations that should trigger it, including the exact phrase people type. The writing-for-agents skill in the same repo spells out the rules I follow: front-load the leading word, write one trigger per distinct case, and collapse synonyms that describe the same case twice. Every word in a description is paid for on every turn, so padding it with "helps you write better tests efficiently" costs context and triggers nothing.
When should a skill point to other files instead of holding everything?
When only some runs need the material. The docs suggest keeping SKILL.md under 500 lines and moving detailed reference to separate files that the skill links, saying what each file contains and when to open it. The agent opens them only when the link's wording matches the task.
In this repo the writing-for-agents skill keeps general writing rules in SKILL.md and sends one branch elsewhere: "When the document you're writing is a skill, read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills." An agent editing a CLAUDE.md has no reason to open that file; one writing a skill does. The blog-post skill does the same with the content strategy: the calendar and backlog live in docs/content-strategy.md, which the team also reads, and the skill holds a pointer to it rather than a copy.
Can one skill call another?
Yes. A skill body can tell the agent to invoke another skill, and that is how I keep shared material in one place. The smallest example in the repo is grill-with-docs. The whole file is seven lines:
---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
disable-model-invocation: true
---
Call the Skill tool twice, for "grilling" and "domain-modeling".The blog-post skill chains in the same way. Its workflow has a step called humanizer pass: run the humanizer skill on the full draft, FAQ and SEO fields, keeping numbers, links and sources unchanged. Humanizer is a 416-line skill I vendored from the open-source blader/humanizer project, with an Italian section added locally. Because it is a separate skill, I also use it for commit messages and docs, and the blog-post skill stays focused on the article.
The tdd skill points to codebase-design when the shape of an interface is in question, and the project CLAUDE.md opens with "TDD, non-negotiable" and names the tdd and testing skills. The rule sits in CLAUDE.md because it applies to every change. The how-to sits in skills because it is only needed when tests are being written.
Should a skill be triggered by Claude or only by you?
Five of the 14 skills in this repo set disable-model-invocation: true: triage, retro, to-tickets, grill-with-docs and improve-codebase-architecture. I start each of them on purpose, and none of them should fire because a sentence in a conversation happened to match. A user-invoked skill costs nothing in context, because its description never enters the listing. The price is that you have to remember it exists.
The other nine are model-invoked. The agent needs to reach testing or tdd on its own whenever it writes code, and other skills need to call humanizer or domain-modeling. If neither the agent nor another skill will ever need to start it, make it user-invoked.
When is a skill the wrong tool?
| You need | Use | Why |
|---|---|---|
| A fact the agent cannot infer ("pnpm only") | A line in CLAUDE.md | It applies to every task, and one line is cheap |
| A guarantee (never read .env files) | A hook or a permission rule | Skills and CLAUDE.md are context, which the model can ignore |
| Something the code already tells (folder layout, scripts) | Nothing | The agent can read package.json; a copy goes stale |
| A procedure used now and then | A skill | The body loads only for that task |
I also skip a skill when the procedure has happened once. Write the skill the second or third time you explain the same thing, when you know which parts the agent gets wrong. My guide on writing a CLAUDE.md covers the other side of this split: what stays in the always-loaded file.
What are the common mistakes when writing Claude Code skills?
The first is a description written for humans ("A helpful skill for blog content") instead of a list of triggers. The skill exists and never loads. The second is putting rules that must hold into a skill: a skill that says "never push to main" is a request, and only a hook or a permission blocks the push. The third is copying reference material into the skill that already lives in a doc the team maintains, so the two drift apart within a month. The fourth is a single 1,000-line skill that covers every branch, which the docs advise against and which buries the steps the agent needs under material it does not. The last is never rereading the skill. Each rule in mine was added after the agent got something wrong, and a rule nobody rereads stays there whether or not it still applies.
The Claude Code mistakes I removed from my workflow show where hooks and review steps take over from written rules.
Want your team's processes in skills your agents use?
I set up Claude Code for engineering teams: skills, CLAUDE.md, hooks and review steps built around how your team already works.
Let's talkIf you are building agents for your business rather than configuring a coding assistant, the same principles apply to system prompts and tool descriptions. That is the work I do in AI agent development.



