Lesson 24 / 26

Anti-Patterns and When Not to Use a Skill

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.

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.

Quick check: 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
  • 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.