Writing a Skill That Actually Triggers

What it is for

A skill that never loads may as well not exist, and the field that decides whether it loads is the description — the one people write last and shortest. This is how to write it so the agent reaches for the skill at the right moment and leaves it alone the rest of the time.

The skill Copy

---
name: your-skill-name
description: Use when <the situation>, including <the symptoms>. Covers <what it does>.
---

A skill that never loads is worse than no skill, because you believe it is
working. Loading is decided almost entirely by `description`, and the body has
no influence on it at all.

Write the description as SITUATIONS, not as a topic:
- Bad:  "Helps with database work."
- Good: "Use when writing or reviewing SQL, when a query is slow, when adding
         an index or a migration, or when an ORM is producing N+1 queries."

Rules that decide whether it fires:
- **Name the symptoms, not only the subject.** People arrive at a skill through
  a problem ("this is slow", "it returns 403 only in production"), not through
  its category. The symptom words are what match.
- **Include the words the user will actually type**, including the wrong ones
  and the informal ones.
- **Say what it does NOT cover**, if a neighbouring skill covers it. Two skills
  competing for one situation is how the wrong one wins.
- **Under about 500 characters.** A long description is diluted, not enriched.

Then test it properly: open a FRESH conversation and describe the problem the
way a user would, without naming the skill. If it does not load, the description
is wrong — do not fix the body.

How to install it Copy

Claude Code / Claude Desktop

1. Create a folder named after the skill inside your skills directory:
   - Claude Code: `~/.claude/skills/<skill-name>/`
   - A project-local skill: `<project>/.claude/skills/<skill-name>/`
2. Save the text below as `SKILL.md` in that folder, keeping the
   `---` frontmatter block at the top — the `name` and `description`
   fields are what make the skill discoverable.
3. Restart Claude Code, or run `/skills` to confirm it is listed.

The skill loads only when its `description` matches what you are doing,
so a precise description matters more than a long body.

Did it work for you?

Where it came from