Claude Code: Lessons from Building Claude Code — How Anthropic Uses Skills

What Claude Code Skills Actually Are

A common misconception treats skills as simple markdown files. According to Anthropic's June 2026 post on lessons learned from building Claude Code, skills are actually folders: they can contain scripts, assets, data files, and structured instructions that agents discover and execute to work more accurately and efficiently across complex tasks.

Nine Categories That Emerged from Internal Audits

After cataloging hundreds of active skills used internally, Anthropic identified nine categories that most skills fall into:

1. Library and API reference: documentation for libraries and CLIs with known edge cases and gotchas
2. Product verification: testing and validation tools specific to a codebase or product
3. Data fetching and analysis: connections into data and monitoring stacks
4. Business process automation: workflow automation commands and pipelines
5. Code scaffolding: framework boilerplates and project generators
6. Code quality and review: enforcement tools and linting utilities
7. CI/CD and deployment: build and deployment automation
8. Runbooks: investigation and troubleshooting guides
9. Infrastructure operations: maintenance and operational procedures

The best-performing skills fit cleanly into a single category. Skills that span multiple categories tend to confuse the agent and underperform.

The Gotchas Section: Highest-Signal Content

The post identifies the Gotchas section as the single most valuable component of any skill. Unlike generic documentation, a Gotchas section is built up over time from real failure points that Claude encounters when using the skill. This approach turns lived experience into structured, actionable knowledge embedded directly in the agent's context.

The recommendation is to start small and update the Gotchas section continuously as new failure modes emerge, treating it as a living document rather than a one-time write.

Avoiding Redundancy

A key principle: Claude already knows how to code and can read the codebase. Skills should focus on novel information (edge cases, environment-specific behavior, third-party API quirks) rather than restating what Claude already knows. Overly prescriptive instructions that try to control every decision tend to reduce adaptability and produce worse outcomes than more targeted guidance.

Progressive Disclosure via Folder Structure

The post recommends using folder structure as a progressive disclosure mechanism. Organizing skills hierarchically helps agents identify relevant sub-skills without loading the entire skill into context, improving both latency and relevance.

Distribution and Measurement

Skills can be distributed through repository integration or shared via the plugin marketplace. The post recommends logging hooks to track which skills are used most frequently, helping teams identify underutilized skills worth improving or deprecating. Usage data also reveals which skills produce the most agent failures, a direct signal for where the Gotchas section needs expansion.