Writing your own skill
skill-writerFREEskillsclaude code
Works out why a skill never fires, and what separates one from a restatement of what the model already does.
Was er tut
- Triggers on “write a skill”, “my skill is being ignored”, “how do I package this workflow”.
- Explains that the front-matter description is not a summary but the trigger: it is the only part read before the skill loads.
- Requires the description to use the words people actually type: “make it not fall apart on mobile”, not “perform responsive verification”.
- Names the two reasons a skill stays silent: the description is not about those situations, or a neighbouring skill wins.
- Demands rules with reasons: a rule without one stops working in the first situation its author did not foresee.
- Keeps it under about two hundred lines: a skill is loaded into working context, and a long one crowds out the thing being worked on. Detail goes into a file beside it.
- Tests honestly: a fresh session, real phrasing, and three questions — did it fire, did the answer change, does it hijack unrelated work.
Wozu er gut ist
Most homemade skills never fire once, and their author never finds out: there is no error, nothing simply happens. The second most common failure is a skill that fires and restates what the model would have done anyway — harmless to the answer, expensive in context. Both take five minutes to detect, if you know what to check.
Wohin damit
- 1Legen Sie im Projekt den Ordner .claude/skills/skill-writer an
- 2Legen Sie dort eine SKILL.md mit dem Text unten ab
- 3Fertig. Claude Code lädt den Skill selbst, sobald eine Aufgabe zur Beschreibung passt
Damit der Skill in allen Projekten statt nur in einem funktioniert, legen Sie ihn in ~/.claude/skills statt in den Projektordner.
SKILL.md-Datei
--- name: skill-writer description: Write a new skill for Claude Code, or fix one that never triggers. Use when the user wants to package a repeatable workflow, asks how to write a skill, or says their skill is being ignored. --- # Writing a skill A skill is instructions Claude loads when a particular kind of task comes up. Two things decide whether it is any use: whether it triggers at the right moment, and whether it says something the model would not have done anyway. ## The front matter decides whether it ever runs ``` --- name: kebab-case-name description: What it does. When to use it. --- ``` The `name` must match the filename. The `description` is the only part read before the skill loads — it is the trigger, not a summary. Write it in two halves: what the skill does, then the situations that should invoke it, in the words a user would actually type. Include the casual phrasings. Somebody says "make the mobile version work", not "perform responsive verification". If a skill never fires, the description is almost always the reason. The second most common reason is that it overlaps another skill and the other one wins. ## The body Write it for someone competent who has not done this particular job here before. That means: - **Rules with reasons.** "Verify the signature over the raw bytes, because reserialising changes key order" survives contact with a situation you did not foresee. "Verify the signature" does not. - **Order, when order matters.** Most skills are a procedure. Number the steps and say what to check before moving on. - **The specific failures.** The three things that always go wrong here are worth more than a complete description of the happy path. - **What not to do,** and why. Prohibitions without reasons get reasoned around. ## Length Under about two hundred lines. A skill is loaded into a working context — a long one crowds out the thing being worked on. If it genuinely needs more, split the detail into a `references/` file beside `SKILL.md` and point to it, so it is read only when needed. ## Test it honestly Start a fresh session and type what a real user would type — not the description. Check three things: 1. Did it trigger? 2. Did the answer differ from what you get without it? If not, the skill is describing what the model already does, and it is costing context for nothing. 3. Does it trigger when it should not? An over-broad description is worse than a narrow one: it hijacks unrelated work. Fix triggering by editing the description. Fix quality by making the body more specific, not longer.