Tips for building good Claude Skills

My notes

Summary

A Claude Code engineer shares three high-leverage tactics for building skills that actually improve over time: maintain a “gotcha” section of past mistakes, use the file system for progressive disclosure instead of stuffing markdown, and avoid over-rigid instructions that railroad the model.

Key Insight

• Gotcha section beats instructions. The list of things Claude has previously done wrong is more valuable than positive instructions. Every time the model misfires while running the skill, log the mistake into the gotcha block. This turns the skill into a feedback loop that compounds rather than a static spec.
• A skill is a folder, not a file. Beyond SKILL.md you can add scripts, references, examples, templates. Progressive disclosure means Claude pulls these in only when needed, they don’t bloat the context window. The main file stays lean; depth lives in side files the model fetches on demand.
• Don’t railroad. Overly rigid step-by-step instructions break when the situation deviates. Provide context and constraints, then let Claude adapt. Constraints over scripts.