How to write an Agent Skill (SKILL.md) — in one evening, no code

The most annoying skill failure goes like this: you write excellent instructions, drop them into the project — and the agent never uses them. Silently. As if the file didn't exist.

Nine times out of ten the body isn't the problem. One line of description is. Let's walk the whole path, and fix that line at step 6.

No code required: an Agent Skill is a folder with a text file in it.

1. Pick something you've explained twice

A good candidate is something you've already repeated across sessions. Not "do it nicely" — an actual procedure:

• how a new component is laid out (folder, files, exports);
• how a release gets prepared before shipping;
• how commit messages are written;
• how a report should be formatted.

The tell for a good topic: the task has a correct order of steps the agent won't guess on its own. No order, no skill needed — a plain prompt will do.

2. Create the folder

Project skills live in .claude/skills/, personal ones in ~/.claude/skills/. We'll do a project one: it ships with the repository and works for the whole team.

mkdir -p .claude/skills/new-component
touch .claude/skills/new-component/SKILL.md

The folder name is lowercase with hyphens. It becomes the name field in a moment.

3. Write the header

Open SKILL.md and start with frontmatter — YAML between two sets of triple dashes:

---
name: new-component
description: Create a new UI component following project conventions. Use when
  asked to add a component, a button, a card, or a new screen.
---

Two fields are required. name — up to 64 characters, lowercase letters, digits and hyphens. description — up to 1024 characters, and it carries all the magic (step 6).

4. Write the body as steps, not wishes

Below that it's ordinary Markdown. Write as if briefing an intern who can code but doesn't know your team's conventions.

When creating a component:

1. Folder `src/components/ProductCard/` — name in PascalCase.
2. Inside, `index.tsx` with a named export. We don't use default exports.
3. Style with tokens from `tokens.css`, never hardcoded colors.
4. Add `ProductCard.test.tsx` next to it with one smoke test.

Don't touch `src/legacy/` — that's the old system.

Three rules separate a working skill from a useless one:

• Concrete paths and names. "In the right folder" is noise; src/components/ is an instruction.
• Prohibitions matter as much as permissions. One "don't touch legacy" line saves hours.
• Keep it short. A skill is read in full once it fires. A 400-line wall dilutes the point — same as in a good prompt.

Got a lot of material? Move the detail into a separate file:

new-component/
├── SKILL.md
└── references/
    └── naming.md

Leave a pointer to it in SKILL.md. The agent opens references/naming.md only if it gets to naming. That's progressive disclosure: you pay for what actually gets read.

5. Check the agent can see it at all

Restart the session — skills are picked up at startup. Then just ask: "which skills do you have available?" Your line should show up in the list.

If it doesn't, check three things: the folder is exactly .claude/skills/, the file is SKILL.md in capitals, and the frontmatter opens and closes with three dashes. A YAML typo is the usual culprit.

6. Test the trigger — and fix the description

Now the real test. Start a new session and phrase the task the way you normally would:

add a product card

The agent should remember the skill on its own. If it doesn't, the problem is description. That's all it sees up front: not a human-facing title, but a trigger condition.

The difference is that the second version contains the words you actually say: "button", "card", "screen". The formula: what it does + when to use it + the user's own words.

Want the opposite — a skill that never fires by itself and waits for your command? Add disable-model-invocation: true to the header and it stays manual, invoked as /new-component.

What you end up with

A 20–30 line file that lives in the repository. New session, new teammate, different machine — the agent still builds the component your way, unprompted.

And a bonus: SKILL.md is an open standard, not a Claude Code feature. The skill moves to another compatible tool as a plain file.

Why is a skill better than a project rules file?

A rules file loads every time, in full — it's for general conventions. A skill is pulled in for a specific task, so it can afford detail you'd otherwise pay context for on every single request. For giving the agent general context, see this guide.

The description is precise and it still doesn't fire. What else?

Check whether a neighbouring skill has a similar description — then the agent is choosing, and it may choose wrong. Separate them by wording: one about components, one about whole screens, no overlap.

What if the skill needs access to an external system?

A skill is instructions; it doesn't go anywhere by itself. If you need live data from a database or a tracker, that's a job for an MCP server — the two approaches are compared in Agent Skills or MCP.