My Claude Code Skills in Production: What the Audit Taught Me

Short summary

The author audited nine Claude Code skills in production and found that one 1,002-line, 25,000-token skill file saturated with MANDATORY/NEVER/LOCKED markers performed worst — because when everything is critical, the model averages priorities instead of arbitrating. Healthy skills stay under 257 lines with critical rules in ten lines max, pushing design justifications and examples into reference files loaded only at the step that needs them. The key lesson: a skill body should be an execution contract, not an encyclopedia, because long-context attention physics buries middle-of-file content under accumulated session tokens.

• •A 25K-token skill file saturated with urgency markers performed worst because the model averages instead of prioritizing
• •Healthy skills stay under 257 lines with critical rules in ten lines max, using reference files for details
• •Skill bodies should be execution contracts, not encyclopedias — attention physics buries mid-file content in long sessions

Generated with AI, which can make mistakes.