This guide is for developers who work with a coding agent, such as Claude Code, and keep explaining the same things at the start of every session. You get a method for writing those things down once, as a skill, in a form the agent applies instead of skimming.
What a skill is
A skill is a folder with a SKILL.md file inside, plus any reference material it needs: palettes, templates, example files. The file opens with a name and a one-line description, then the instructions. The agent reads the description to decide when the skill applies, and the body when it does.
That makes the description the most important line in the file. If it is vague, the skill loads when it should not, or never loads at all.
Start from the scope, not from the content
Before writing a rule, write down where the skill applies and where it does not. Our design skill for this website says, in its description, that it is for the website and not for the interface of our plugins or web apps. We learned to add that line after the first time it was applied where it did not belong.
A good scope answers three questions:
- which project, folder or kind of file it covers;
- which similar work it does not cover;
- what to do when the two overlap.
Write rules with their reasons
A rule without a reason gets followed literally, and broken the first time a case does not fit. A rule with a reason gets applied to cases you did not foresee.
Compare:
- “Do not load fonts from Google.”
- “Do not load fonts from Google: it sends the visitor’s IP address to a third party, which is a privacy problem in the EU. Fonts are served from the theme folder.”
The second tells the agent what is at stake, so it also refuses a font CDN you never named.
Prefer examples to adjectives
“Clean”, “modern” and “elegant” mean nothing to an agent, and little to people. Give it the thing itself:
- the exact color values, as tokens it can copy;
- a reference page that already looks right;
- a short before and after for the mistakes you have already seen.
When a skill covers a visual language, a working reference file is worth more than a page of description. Ours points to an HTML page where every component already runs.
Say what to measure
Agents, like people, tend to declare something done because it looks done. If a rule can be checked, say how: a contrast ratio to compute, a size to read from the browser, a command to run. “Text must be readable” invites a guess; “text contrast at least 4.5:1, computed, not estimated” invites a measurement.
Keep it short enough to be read
A skill competes for attention with the task in front of the agent. Put the rules that prevent real damage first. Move long reference material, like a full palette or a component catalogue, into separate files the skill points to, so it is read only when needed.
Keep it alive
A skill goes stale the same way documentation does: silently. When the agent gets something wrong that the skill should have prevented, fix the skill in the same session, while the reason is fresh. When a rule turns out to be wrong, change it and keep a line saying what it replaced and why, so nobody brings the old one back.
A minimal skeleton
---
name: project-ui
description: Visual language and components of the Example website. Not for the admin screens of the Example plugins.
---
## Scope
Applies to the theme in wp-content/themes/example/. Does not apply to plugin admin screens, which have their own design.
## Rules that prevent damage
- No external resources (fonts, scripts, images): privacy, and the Content-Security-Policy blocks them anyway.
- Text contrast at least 4.5:1. Compute it; do not judge it by eye.
## Tokens
See tokens.css in this folder. Use the variables, never raw color values.
## Reference
reference/home.html shows every component working.