Anthropic Engineer Details Best Practices for Building and Deploying Claude Code Skills

Thariq Shihipar, an engineer on Anthropic's Claude Code team, has shared insights into developing and utilizing "Skills" within the AI agent platform. Shihipar, who played a key role in the Skills feature, outlined a systematic approach for creating, writing, and distributing these extensions, drawing from Anthropic's internal use of hundreds of Skills.

Portrait of Thariq Shihipar, Anthropic engineer.

Skills serve as a primary extension point in Claude Code, offering flexibility in creation and distribution. Despite their versatility, determining optimal usage can be challenging. Anthropic's internal experience has led to a classification system and writing techniques aimed at accelerating development processes.

Understanding Claude Code Skills

Skills are more than simple markdown files; they are folders capable of containing scripts, resource files, and data that agents can discover and use. Claude Code Skills also feature extensive configuration options, including the ability to register dynamic hooks. The most effective Skills often leverage these configurations and folder structures creatively.

Digital representation of a complex folder structure for AI skills.

Categorization of Effective Skills

Anthropic's internal review identified several recurring categories for Skills, noting that the most effective ones typically fit clearly into a single category. This framework helps teams identify potential gaps in their Skill development.

Library and API References: These Skills assist in the correct use of libraries, command-line tools, or SDKs, including internal or commonly misused external libraries. They often contain reference code snippets and lists of common pitfalls for Claude to avoid. Examples include Skills for internal billing libraries, command-line interface tools, and frontend design systems.

Product Validation: Focused on testing and validating code functionality, these Skills often integrate with external tools like Playwright or tmux. Validation Skills are crucial for ensuring the accuracy of Claude's output and can involve techniques such as recording video of output processes or enforcing programmatic state assertions.

Data Retrieval and Analysis: These Skills connect to data and monitoring systems, providing data retrieval libraries with credentials, dashboard IDs, and instructions for common workflows. Examples include Skills for querying conversion funnels, comparing user cohorts, and interacting with Grafana.

Business Processes and Team Automation: Designed to automate repetitive workflows, these Skills often have simple instructions but may depend on other Skills or the Model Context Protocol (MCP). Storing execution results in log files helps models maintain consistency. Examples include Skills for generating standup reports, creating tickets in issue tracking systems, and compiling weekly recaps.

Code Scaffolding and Templates: These Skills generate boilerplate code for specific functionalities, often combining with scripts. They are particularly useful when scaffolding requires natural language specifications beyond pure code. Examples include Skills for setting up new framework workflows, database migration file templates, and creating new internal applications.

Code Quality and Review: These Skills enforce code quality standards and aid in code reviews, often using deterministic scripts or tools. They can be integrated into hooks or GitHub Actions. An "adversarial-review" Skill, for instance, can launch a subagent to find flaws and iterate on fixes.

CI/CD and Deployment: These Skills facilitate code pulling, pushing, and deployment, sometimes referencing other Skills for data collection. Examples include Skills for monitoring pull requests, deploying services with automated rollbacks, and cherry-picking changes for production.

Runbooks: These Skills guide users through multi-tool troubleshooting processes based on observations like alerts or error signatures, ultimately generating structured reports. Examples include Skills for service debugging, on-call procedures, and log correlation.

Infrastructure Operations: These Skills handle routine maintenance and operational tasks, including those with destructive potential, by incorporating safety guardrails. Examples include Skills for identifying orphaned resources, managing dependency approval workflows, and investigating cost spikes.

Abstract visualization of categorized AI skills modules.

Best Practices for Skill Development

When building Skills, several practices can enhance their effectiveness:

Avoid Redundancy: Focus on providing information that challenges Claude's conventional understanding rather than stating obvious programming knowledge. The "frontend-design" Skill, for example, was developed to refine Claude's design aesthetic beyond common clichés.

Incorporate "Gotchas": A critical section of any Skill is the "gotchas" list, which should document common failure points Claude encounters. This section should be continuously updated as new edge cases emerge.

Leverage File System for Context Engineering: Skills are folders, not just single files. Utilizing the entire file system for context engineering and progressive disclosure allows Claude to read detailed information only when necessary, optimizing context window usage. This can involve separating detailed signatures into reference files or storing templates in asset folders.

Maintain Flexibility: While providing necessary information, avoid overly restrictive instructions. Skills should allow Claude the flexibility to adapt to specific situations.

Consider Initial Setup: For Skills requiring user context, such as a Slack channel for posting standup content, initial setup can be managed via a config.json file within the Skill directory. The AskUserQuestion tool can be used for structured multiple-choice interactions.

Optimize description Field: The description field for a Skill should indicate when the Skill should be triggered, rather than merely summarizing its function. This helps Claude determine if a Skill is relevant to a given request.

Implement Memory and Data Storage: Skills can achieve a form of memory by storing data internally, using simple text logs, JSON files, or SQLite databases. For example, a standup-post Skill could record past reports to inform future actions. Data should be stored in a stable directory like ${CLAUDE_PLUGIN_DATA} to prevent loss during Skill upgrades.

Provide Scripts and Generate Code: Giving Claude access to scripts and libraries allows it to focus on orchestration rather than reconstructing boilerplate code. This enables more complex analyses by combining helper functions.

Utilize On-Demand Hooks: Skills can include hooks that activate only when the Skill is called and remain active for the session. This is suitable for subjective actions, such as a /careful hook that intercepts dangerous commands or a /freeze hook that restricts write operations during debugging.

Developer typing code, symbolizing AI skill distribution and management.

Skill Distribution and Management

Skills can be shared by committing them to a code repository under ./.claude/skills or by creating them as plugins for a Claude Code Plugin Marketplace. For smaller teams, repository commits suffice, but a marketplace allows for scalable distribution where team members can install relevant Skills.

Managing a plugin marketplace involves allowing useful Skills to emerge organically. Authors can upload Skills to a sandbox and recommend them, with a formal submission to the marketplace occurring once a Skill gains traction. A review mechanism is advised to prevent the proliferation of low-quality or duplicate Skills.

While direct dependency management between Skills is not currently supported in the plugin marketplace, Skills can reference each other by name if installed.

Abstract data visualization showing skill effectiveness metrics.

Measuring Skill Effectiveness

To assess Skill performance, Anthropic uses a PreToolUse hook to log Skill usage internally. This data helps identify popular Skills and those that are underutilized.

Shihipar emphasized that these insights are practical tips from Anthropic's experience, not an authoritative guide. He encouraged users to experiment and build their own Skills, noting that many internal Skills began as simple text and evolved through continuous refinement based on encountered edge cases.