Three Tips for Building Better Claude Code Skills

A Claude Code engineer shared three practical tips for building skills that actually improve over time. These are not about the initial prompt -- they are about the structure and philosophy behind a skill that gets better the more you use it.

Build a Gotcha Section

One of the most important parts of a skill is not the instructions themselves. It is a list of things Claude has repeatedly done wrong that you do not want it to do again. When you are working through a process and Claude makes a mistake or does something you do not like, add it to the gotcha section. This is the mechanism through which a skill actually improves over time.

Use the File System for Progressive Disclosure

A skill is not just a markdown file -- it is a folder. Beyond the main prompt, you can include scripts, references, examples, and templates. These additional files do not clutter your context window because of progressive disclosure: Claude references them and brings them in only as needed during execution.

Avoid Railroading Claude

If instructions are too rigid, Claude struggles to adapt. The better approach is to give Claude the context and constraints it needs but leave room for it to adapt to the specific situation when the skill is invoked. Overly prescriptive instructions create brittleness.

Key Takeaways

• Add a "gotcha" section to track and prevent recurring mistakes
• A skill is a folder, not just a file -- use scripts, references, examples, and templates
• Progressive disclosure keeps context windows clean by loading files only when needed
• Avoid overly rigid instructions -- give context and constraints, but let Claude adapt

Resources

• Claude Code Skills Documentation -- Official docs on building Claude Code skills
• @maven_hq on TikTok -- Engineering tips for Claude Code workflows