Lessons from building Claude Code: How we use skills

2026-06-03 · Source: Claude Blog · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Intermediate, long

Summary

Anthropic shares lessons from building and scaling hundreds of "skills" within Claude Code, which are defined as folders of instructions, scripts, and resources that agents discover and use for improved accuracy and efficiency. Internally, these skills have become a primary extension point due to their flexibility and ease of distribution. Anthropic categorized its internal skills into nine distinct types: Library and API reference, Product verification, Data fetching and analysis, Business process and team automation, Code scaffolding and templates, Code quality and review, CI/CD and deployment, Runbooks, and Infrastructure operations. The article emphasizes that effective skills often fit cleanly into one category and leverage configuration options and folder structures. Key tips include building "gotchas" sections, using the file system for progressive disclosure, and storing scripts for composition.

Key takeaway

For AI Engineers building agents with Claude Code, focus on structuring skills as categorized folders containing instructions, scripts, and data. Prioritize "gotchas" sections and use the file system for progressive disclosure to enhance agent performance. Consider implementing verification skills, which have shown measurable impact on output quality, and leverage persistent data storage for agent memory. This approach will improve agent consistency and reduce common failure points.

Key insights

Skills are structured folders of instructions, scripts, and resources that enhance agent accuracy and efficiency.

Principles

• Skills are folders, not just markdown files.
• Categorize skills to avoid agent confusion.
• "Gotchas" sections provide high-signal content.

Method

Organize skills using the file system for progressive disclosure, store setup information in a config.json file, and leverage the \${CLAUDE_PLUGIN_DATA} environment variable for persistent memory.

In practice

• Include reference code snippets and gotchas.
• Use scripts for verification and assertions.
• Store data in skills for agent memory.

Topics

• Claude Code
• Agent Skills
• LLM Engineering
• AI Agent Development
• Code Automation
• MLOps

Code references

• anthropics/skills

Best for: AI Engineer, Machine Learning Engineer, MLOps Engineer

Related on AIssential

• Building Agent Skills for Claude Code - Live Workshop — Mastering Claude Code Skills enables consistent, repeatable AI workflows beyond basic prompting.
• How to Write Robust Code with Claude Code — Automated robustness in agent-generated code is achievable through structured prompting and verification.
• Getting the most out of Claude Code — Claude Code's subagents, skills, and context files enable specialized, modular, and persistent AI assistance for coding.
• How I deleted 95% of my agent skills and got better results — Nick Nisi, WorkOS — Agent performance improves by enforcing actions with code, guiding with specific "gotchas," and rigorously measuring outcomes, not by comprehensive instruction.
• Claude Skills Explained: Build, Configure, and Use Custom Skills on Claude Code — Claude Skills enable consistent, reusable AI workflows by defining specific instructions and metadata for automated invocation.
• Claude Code’s 5-Layer Agent Development Kit: The Architecture Most Engineers Are Missing — Claude Code is an agent development kit with a layered architecture for robust, scalable agent behavior.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Claude Blog.