# Anti-Patterns and When Not to Use a Skill — Claude Code Skills & SKILL.md

Source: https://www.geekswithgeeks.com/en/claude-code-skills/p-anti

> Avoid the common mistakes that make skills useless or harmful.

## Common mistakes

Frequent anti-patterns: a **vague description** so the skill never triggers; a **giant SKILL.md** that restates the whole documentation; **duplicating CLAUDE.md** content that should simply live there; **instructions that depend on the model remembering** a rule that a **hook or script** could enforce; **over-prescribing** every micro-step, so Claude cannot adapt when the situation differs; **no verification step** ("done" without checking); **stale commands and paths** that no longer exist; **overlapping skills** whose descriptions compete; **broad `allowed-tools`**; and **secrets in files**. Also know when **not** to write a skill: a one-off task you will never repeat; a fact needed in every session (use CLAUDE.md); a rule that must never be broken (use a hook, permission setting or CI check); or something the model already does well without help. Start small: capture a procedure you have explained three times, test it, and grow it only when real use shows a gap.

## Anti-pattern fixes

Common problems and what to do instead.

```text
Anti-pattern                          Instead
vague description                      what + when + trigger phrases, tested with real requests
1500-line SKILL.md                      short body; details in references/ loaded on demand
rule "always run prettier"              a hook (deterministic), not a hopeful sentence
every micro-step dictated               give goal, constraints, checks; let Claude adapt
no "how to verify"                      a verification step with a script or checklist
stale paths/commands                    update the skill in the same PR as the change
broad allowed-tools                     specific scripts only, read-only where possible
```

## Delete skills nobody uses

Unused skills still cost description tokens and risk firing by mistake.

**Quiz:** A formatting rule must apply after every edit with no exceptions. Which is best?

- [ ] A longer description
- [ ] A sentence in a skill hoping Claude remembers
- [x] A hook that runs the formatter deterministically
- [ ] A bigger context window

*Answer:* A hook that runs the formatter deterministically. Use deterministic enforcement for rules that must always hold.