How to Build Claude Code Skills That Actually Work

Author: the_enterprise.ai

A practitioner's guide to building Claude Code skills after three months of iteration. The early attempts were poor. The lessons that followed cover folder structure, progressive disclosure, gotcha documentation, flexibility versus rigidity, description fields, config management, and stable storage.

Skills Are Folders, Not Files

A skill is a folder, not a single markdown file. Inside that folder, the main instructions sit alongside helper scripts, reference code, templates, and config files. This structure lets you organize complexity without cramming everything into one document.

Progressive Disclosure

The most important structural decision. Do not dump all instructions into one massive file. Instead, list what files exist in the skill folder and let Claude read them only when the situation requires it. This keeps the context window clean and prevents information overload.

The Gotcha Section Is the Real Intelligence

Every time Claude makes a mistake while using a skill, document that failure. Wrong function call. Missing required field. Bad assumption that broke something. Capture all of it. Over time, this gotcha section becomes the most valuable part of the skill because it prevents repeated failures. The accumulated error history teaches Claude what not to do.

Do Not Over-Control the Agent

An early mistake was writing instructions that were too specific, essentially railroading Claude into one exact execution path. That approach breaks down because skills get reused across different situations. The fix: provide the information Claude needs but leave flexibility for it to adapt. Guidance over rigid paths.

Write Descriptions as Trigger Conditions

The description field on a skill is not for humans. Claude scans every skill description at session start to decide which one to use. Write it like a trigger condition that tells Claude when to activate the skill, not a human-readable summary of what the skill does.

Config Files for User-Specific Context

If a skill needs user-specific information, like which Slack channel to post to, store that in a config file. On first run, Claude asks the user and saves the answer. Every subsequent run reads the config and moves on. No repeated questions.

Use Stable Storage for Persistent Data

Never save persistent data inside the skill folder itself. That data gets wiped on upgrades. Use the stable plugin data directory instead. The skill folder is for instructions and templates. The plugin data directory is for anything that needs to survive between versions.

Distribution: Repo First, Marketplace Later

Share skills by checking them into the team repo. Only move a skill to an internal marketplace after it has real traction and people are actually using it. Premature publishing creates clutter. A bit of curation before distribution goes a long way.

Key Takeaways

• Structure skills as folders with progressive disclosure, not monolithic markdown files
• The gotcha section, where you document every Claude failure, becomes the most valuable part of any skill over time
• Rigid instructions break reuse; give guidance and information, not step-by-step railroad tracks
• Skill descriptions are for Claude, not for you; write them as trigger conditions
• Store persistent data in the plugin data directory, never inside the skill folder
• Start with a few lines and one gotcha, then grow the skill incrementally as edge cases surface