Takeaways
- A skill is a folder with a
SKILL.mdfile: a short description the agent reads to decide when to load it, and a body it reads once it has. - Skills are loaded on demand. Rules files like
CLAUDE.mdor.cursor/rulesare loaded always. Put taste in skills, put facts in rules. - One skill covers one aspect of the work. "Design" is not a skill. "Animation timing" is.
- Write rules as paired decisions, right beside wrong, with the reason. Principles alone get nodded at and ignored.
- Install by copying the folder. Invoke by name, or let the description trigger it. Test by watching whether the output actually changed.
The problem skills solve
Every conversation with a coding agent starts from zero. You explain that hover transitions run 150ms, that borders are alpha not hex, that emoji are not icons. The agent agrees, does it, and next session you explain it again. Pasting a long prompt each time works until the prompt is two thousand words and you are the only one who has it.
Rules files were the first fix. A CLAUDE.md or AGENTS.md in the repo is read at the start of every session. That is right for facts about the project: where the vault lives, which package manager, that /de routes are disabled. It is wrong for craft. A page of animation rules loaded into a session about a database migration is noise, and noise gets skimmed.
A skill is the second fix. It is loaded only when the task matches, so it can be long, specific and opinionated without costing anything the rest of the time.
What a skill is, concretely
A skill is a directory containing a SKILL.md. The file has two parts.
Frontmatter with a name and a description. The description is the only part the agent sees before deciding whether to load the skill, so it has to say what the skill is for in one or two sentences a router can match against: "Interface animation: whether to animate, easing, duration, springs, enter and exit".
Body with the instructions. This is the part that changes behaviour. It can be a few hundred words or a few thousand, and it can link to sibling files in the same folder for reference material the agent should read only when it needs it: an easing curve library, a picker spec, a checklist.
The example below is the whole thing. Nothing is hidden.
Skills versus prompts versus rules
| Loaded | Good for | Bad for | |
|---|---|---|---|
Rules file (CLAUDE.md, .cursor/rules) | Every session | Project facts, conventions, paths, "never do X" | Long craft guidance nobody needs today |
Skill (SKILL.md) | When the task matches | Taste, process, checklists, one domain at a time | Facts that must always be true |
| Prompt (pasted text) | When you paste it | One-off shape of a single answer | Anything you will want twice |
A prompt you have pasted three times is a skill waiting to be written. A skill everyone needs in every session is a rules file.
How to use one
Install. Copy the folder into the place your agent reads from. In Claude Code that is ~/.claude/skills/<name>/ for yourself or .claude/skills/<name>/ for the repo. Cursor reads .cursor/rules/ and Codex reads AGENTS.md, so a skill written for one usually needs a small wrapper for the others. Tools like npx skills add do the copying for you.
Invoke. Type /<name> at the start of a request, with the request after it: /emil-animations review the theme switch. The agent loads the body and works under it for that turn.
Let it trigger. If the description is specific, the agent loads the skill itself when the task matches. This is why the description matters more than the name: "UI polish" triggers on almost nothing, "font rendering, tabular numbers, hover states that shift layout, hit areas" triggers on the right things.
Stack, do not pile. Two or three skills in sequence work. Five at once do not. Each one carries a craft bar, and an agent given five bars applies none of them properly. Foundations first, then the material, then a review pass.
Writing a skill that changes behaviour
Most skills fail the same way: they read like a values statement. "Prioritise accessibility." "Keep it simple." The agent already agrees with those. Nothing in its output changes.
One aspect per skill. A skill that covers layout and colour and motion is a document, not a tool. Split it. The agent picks the right one by description, and you can improve one without touching the others.
Rules as pairs. Put the wrong choice next to the right one and say why. "Hover transitions: 150ms feels native; 400ms feels like the UI is thinking." That is a decision the agent can make. "Use appropriate durations" is not.
Numbers, not adjectives. Scale 0.96 on press, never below 0.95. Body text capped at 65ch. Exit 20 to 30 percent faster than enter. An adjective gets interpreted; a number gets applied.
Say when to break the rule. A skill that only lists rules produces an agent that applies them where they do not belong. Baseline grids are an editorial tool, overkill in dense product UI. Say so.
Decide what phase it belongs to. Deciding, building, refining, checking. A polish skill run before the layout is settled gets its work thrown away. Put the phase in the description so the router can tell.
Keep instructions in the body. If the body says "see the style guide", the agent has to find the style guide. Put the rule in the skill and link out only for reference tables it should read on demand.
Common mistakes
- Restating the framework. A skill that says "use Tailwind utilities" in a Tailwind repo adds nothing. Skills carry what the codebase does not already show.
- Hedged rules. "Consider using alpha borders where appropriate." The agent will consider it and move on. "Light-mode borders are
rgba(0,0,0,0.08), never a solid hex" gets applied. - A description that matches everything. The agent loads it on every task, which is the rules-file failure again with extra steps.
- No review pass. The first draft of a skill is your memory of the rules. Run it on real work, look at what the agent still gets wrong, and write that down as the next pair.
How to tell whether it works
Run the same request with and without the skill and compare the output. If you cannot point at a difference, the skill is a values statement. Rewrite the vaguest rule as a pair with a number, and run it again. A skill is finished when the agent's output looks like work you would have done yourself, not when the document is complete.
---
name: press-feedback
description: Pressed states on buttons and cards — scale, timing, when to skip it. Load when adding or reviewing click feedback.
---
# Press feedback
Buttons need a pressed state. Without it the button feels dead.
- Scale to 0.96 on :active. Never below 0.95 — it looks exaggerated.
- Use a CSS transition, 150ms ease-out, so releasing mid-press returns smoothly. Not a keyframe.
- Skip it on high-frequency controls (list rows, keyboard-driven menus). Speed beats feedback there.
- Respect prefers-reduced-motion: no scale at all.
Wrong: `transition: all 300ms` + `scale(0.9)`
Right: `transition: scale 150ms ease-out` + `scale: 0.96`