Every skill author hits these. The good news is they all have the same shape — a trigger that's too wide or too narrow, a body that's doing too much, or a path baked into a place it doesn't belong. Spot the pattern, apply the fix.
Most skill bugs aren't bugs in the code. They're misjudgements in the trigger or the shape of the body. The same eight problems crop up over and over — so over and over that you can almost diagnose a struggling skill from across the room.
This chapter walks through each of the eight, shows the exact mistake, and gives the fix. Then three widgets let you practice spotting them in the wild.
Before we dig in, here are all eight side by side. Skim, then dive — every one gets a section below.
| # | Pitfall | What it looks like | The fix |
|---|---|---|---|
| P1 | Trigger too broad | "helps with anything text" | Name the verbs and nouns |
| P2 | Trigger too narrow | One exact phrase only | 3-5 natural variations |
| P3 | Hardcoded user paths | /Users/alice/... | Parameterise or document |
| P4 | SKILL.md doing too much | 800-line body | Move to references/ |
| P5 | Stale supporting files | SKILL.md and refs disagree | Version as one unit |
| P6 | Skill conflicts | Two skills, same trigger | Tighten, skip, or merge |
| P7 | Mixing concerns | Four jobs in one skill | Split, one job each |
| P8 | Non-portability | Assumes node, make, mac | Declare deps, fail loudly |
The classic enthusiastic mistake. You wrote a skill, you want it to fire, so you tell Claude to use it generously.
description: "helps with anything related to text". It fires for every message anyone ever sends. Suddenly Claude tries to use your skill to reply "hello", to plan a trip, to debug Python — because all of those involve text.The skill becomes noise. Worse, it competes with every other skill, so genuine matches get muddied too.
The over-correction. You learned that broad triggers misfire, so you locked the trigger to one exact phrase.
description: "Use when user says exactly 'pls generate TOC'". Real users never type that exact string. They say "make a TOC", "generate a table of contents", "build a TOC from these headings". The skill never fires.Same outcome as too-broad: the skill is useless. Different shape, same result.
The skill body says /Users/alice/.config/foo.json. Works perfectly for Alice. Breaks the moment anyone else tries to use it.
/Users/alice/, /home/bob/, C:\Users\carol\ — that's a portability bomb. Even if you're the only user today, future-you on a new machine has the same problem.~/ or $HOME. Refer to "your deploy target (configured in references/targets.md)" rather than spelling out one user's filesystem. For strictly-personal skills it's fine to hardcode; for anything you might share, never.The most common quality-of-life pitfall. The skill works — but it's 800 lines, includes the whole reference table inline, and ships with a 40-line sample dataset baked into the body.
references/X.md, templates/Y.md, scripts/Z.sh, and have SKILL.md link to them. Claude follows the link with the Read tool only when actually needed. Short SKILL.md, deep references — that's the shape.You did the right thing — moved detail into references/. Then you updated SKILL.md to point at a new workflow, but references/old-decisions.md still describes the old one. Now SKILL.md and the references contradict each other.
references/run.md describes the old slow path. Claude reads both and either picks the wrong one or asks the user to clarify a contradiction that shouldn't exist.Two skills with overlapping triggers. web-scraper says "use for any data from a webpage". screenshot-tool says "use to capture anything from a webpage". The user asks "grab the data from this page" — and Claude has two reasonable matches.
A single skill named editor-helper that triggers on rename, refactor, format, and extract-function. It tries to cover the entire editor toolkit in one file.
editor-helper into rename-symbol, refactor-function, format-code, extract-function. Each has a focused trigger and a focused body. Easier to write, easier to test, easier to compose.Cousin to pitfall 3, but about tools rather than paths. Your skill assumes node is on PATH. Or that make exists. Or that the user is on macOS and has pbcopy. Works for you. Breaks for everyone else, and the failure is silent — Claude just produces a worse output.
make build". Half your users are on Windows and don't have make. The skill quietly degrades into "give up and apologise".Five SKILL.md snippets. Each has exactly one thing wrong with it. Pick the pitfall from the four options; the reveal explains the fix.
For each pitfall, see the broken SKILL.md side by side with the fixed version. The red bits are the problem; the green bits are the cure.
Paste a SKILL.md into the box. The widget scans for known pitfall patterns and tells you how many it found. None of this is rocket science — it's the same patterns you'd look for if you reviewed your own skill out loud.
Three small SKILL.md snippets, broken on the left tab, fixed on the right. The same shape of bug shows up in real skills constantly — these are the patterns to recognise.