Use skills properly: common mistakes

Two other guides already cover the fundamentals: what a skill actually is, and how to build one from scratch. This one is about what goes wrong after you have built it. Skills fail in a small number of predictable ways, and almost all of them trace back to one of two places: the description, or the instructions. A bad description means the skill fires when it should not, or stays silent on a request it should have caught. Bad instructions waste the model's attention once the skill does load, or quietly go stale while the process underneath keeps changing. None of these mistakes are exotic. They are the ordinary failure modes of anything written once and assumed to keep working on its own, and every one of them has a specific, checkable fix.

Mistake 1: The description is too broad

A description written to cover the general subject instead of the specific job will fire on requests that have nothing to do with it. "Assists with anything code-related" catches a request to explain a for-loop, rename a variable, or draft a commit message, three tasks with no business sharing one skill. This happens because writing broad feels safe, a wide net looks like it will not miss anything. But a model choosing one skill out of dozens reads breadth as a weak signal, not a strong one, and a skill that answers to everything ends up answering to nothing well. The fix is to name the actual trigger: the file types, the phrases a real request would contain, the specific situation, not the general category it happens to live in.

description: >
  Assists with anything code-related: reviewing, writing,
  explaining, or refactoring.

description: >
  Reviews a pull request diff against our team's style guide
  and flags violations. Use when the user pastes a diff, asks
  for a code review, or mentions a PR.

Mistake 2: The description is too narrow, or just vague

This mistake has two different causes that produce the same symptom: the skill never fires, even on requests it was clearly built for. Vague is the more common one. Anthropic's own best-practices guidance lists this exact failure with three examples of what not to write: "Helps with documents", "Processes data", "Does stuff with files".² None of those three tells the model what situation should trigger it, so nothing reliably does. The second cause is the opposite problem dressed up as precision: a description that only matches one exact phrase, for instance a changelog skill that fires on "format my changelog" but stays silent on "clean up these commit logs into release notes," a request asking for the same thing in different words. Fix vague by naming the job and the trigger together. Fix narrow by writing the description around the situation, not one exact sentence, and including a few of the ways a real person actually phrases the request.

Mistake 3: One skill is quietly doing three jobs

A skill covering everything under one broad heading, releases, say, ends up with a description too general to match cleanly and instructions too long for any single use. It happens because the jobs feel related on the surface even when they are not: formatting a changelog, writing a commit message, and drafting a release announcement all touch "release," but each has its own format, its own audience, and its own trigger phrase. Anthropic's own engineering guidance makes the token case for splitting directly: when contexts are mutually exclusive or rarely used together, keeping them as separate paths reduces the tokens any single request has to load.³ The fix is the same test covered in the build guide: say the skill's job out loud in one sentence. If you need the word "and" to finish that sentence, it is two skills, not one, and each should get its own file, its own description, and its own name.

Mistake 4: The instructions re-teach the model what it already knows

Once a skill triggers, its instructions load into the same context window as everything else in the conversation, and every paragraph in there competes for the model's attention, it does not sit free on the sidelines. A paragraph explaining what a PDF is, or what a pivot table does, is not helping. It is spending tokens on something the model already knows, leaving less room for the one thing it does not: your team's exact format, the rule you always end up repeating, the exception nobody remembers until it bites. Anthropic's own comparison makes the cost concrete: a concise instruction for extracting PDF text runs about 50 tokens, while a version padded with background on what PDFs are and why a particular library is recommended runs about 150, three times the cost for the same instruction.² The fix is to challenge every paragraph before it goes in: does this justify its token cost, or does the model already know it?

Mistake 5: Nobody tested whether it actually triggers

A skill that has never been tested is a guess about how the model reads your description, and guesses tend to be wrong in a specific, unglamorous way: quietly, on requests you never thought to try. It happens because testing feels like extra work once the skill is written and the one example that inspired it already works. That single success is not evidence, it is confirmation bias with a file extension. Anthropic's own checklist for sharing a skill sets a real floor: at least three test scenarios before you trust it, and testing across every model size you plan to use it with, since a skill tuned for a stronger model can under-explain for a faster, cheaper one.² Run an obvious hit, a near miss that should stay quiet, and a request that mentions the general topic without needing this specific skill. If any of the three goes wrong, fix the description first, not the instructions.

Mistake 6: The name does not say what the skill does

A skills folder full of "helper", "utils", and "tools-v2" is unreadable, to you, to a teammate, and to the model choosing among however many skills are installed. Nobody can tell what any of them do from the name alone, which means someone eventually writes a duplicate rather than search for one they cannot identify. It happens because a skill gets named quickly mid-task, after the tool it happens to use, rather than the job it does for whoever reads the name later. Anthropic's naming guidance is specific: use gerund form, a verb plus "-ing," so the name reads as an activity, processing-pdfs, writing-commit-messages, formatting-changelogs, and avoid vague names like "helper" or "utils," overly generic ones like "documents" or "data," and reserved words like "claude" or "anthropic."² A name that fails that test is worth fixing even after the skill works well, since the cost here is not correctness, it is discoverability.

Mistake 7: The skill goes stale

A skill that still triggers correctly can still be wrong, because the instructions inside it describe a process that used to be true. An API endpoint moved, a deadline passed, your team dropped a step nobody removed from the file. The model reads whatever is on disk and treats it as current, because nothing tells it otherwise. This happens because a skill has no natural owner after it ships. Anthropic's own content guidance addresses the sharpest version directly: a date-bound line like "if you're doing this before August 2025, use the old API" guarantees the skill goes wrong on a specific future date, and it recommends a "current method" section plus a collapsed "old patterns" section instead, so nothing in the main instructions carries a built-in expiration.² The rest of the fix is behavioral, not textual: treat a skill like living documentation, and revisit it when the process changes. Anthropic frames the same habit as an ongoing loop, watching how a skill performs in real use and revising it based on what actually happens, not what you assumed when you wrote it.³

Read next: for the concept and the judgment call on whether a task is worth a skill at all, see What skills are, and when to use one. For the hands-on build, spotting the repeated task, writing the description, bundling files, and testing before you trust it, see Create a skill from scratch.