The Complete Guide to Claude Code Skills: Lessons from Anthropic’s Engineering Team
Introduction
If you are using Claude Code for development work, you have likely encountered the Skills feature. As one of the most frequently used extension points in Claude Code, Skills have gained popularity among developers due to their flexibility and ease of use.
The engineering team at Anthropic uses hundreds of Skills in their daily development work, and these tools have significantly improved their development efficiency. This article shares the lessons they have learned from practical usage, helping you better understand and utilize this powerful feature.
What Exactly Are Skills?
When people first encounter Skills, they often assume they are simply Markdown files. In reality, a Skill is a complete folder structure that can contain scripts, resource files, data, and more. Claude can actively discover, explore, and manipulate these contents.
In Claude Code, Skills also come with a configuration system that supports registering dynamic hooks, allowing Skills to extend far beyond the capabilities of static documentation.
The Nine Types of Practical Skills
Based on the classification used by the Anthropic team, Skills can be organized into nine primary types. Understanding these categories helps you identify whether your team is missing any critical scenarios.
1. Library and API Reference Skills
These Skills explain how to correctly use specific libraries, command-line tools, or SDKs. They apply to both internally developed libraries and common third-party libraries that Claude may struggle with during standard usage.
These Skills typically include a folder of reference code snippets and a list of common pitfalls that Claude should avoid when writing scripts.
Typical Application Scenarios:
2. Product Verification Skills
These Skills describe how to test or verify that code is working correctly. They are often paired with external tools such as Playwright or Tmux to perform actual verification operations.
Verification Skills are crucial for ensuring the quality of Claude’s output. The Anthropic team even suggests that it is worth spending a week specifically to perfect these Skills.
Practical Techniques:
- ▸
Have Claude record videos of the testing process for later review - ▸
Enforce programmatic state assertions at each step - ▸
Include multiple scripts in the Skill to support different verification scenarios
Example Scenarios:
- ▸
Signup flow driver: Runs through registration → email verification → onboarding in a headless browser, with state assertion hooks at each step - ▸
Checkout verifier: Drives the checkout UI using Stripe test cards, verifying that the invoice reaches the correct final state - ▸
Tmux CLI driver: For interactive CLI testing where the target requires a TTY
3. Data Fetching and Analysis Skills
These Skills connect to your team’s data and monitoring infrastructure. They may include libraries for fetching data (with credentials), specific dashboard IDs, and instructions for common workflows.
Typical Applications:
- ▸
Funnel query: Explains which events to join to view the “signup → activation → paid” conversion path, and identifies the table containing the canonical user_id - ▸
Cohort comparison: Compares retention or conversion rates between two cohorts, flags statistically significant differences, and links to segment definitions - ▸
Grafana integration: Data source UIDs, cluster names, and a lookup table mapping problems to dashboards
4. Business Process and Team Automation Skills
These Skills simplify repetitive workflows into single commands. While the instructions themselves are usually straightforward, they may depend on other Skills or MCPs for complex functionality.
For these Skills, storing historical execution results in log files helps the model maintain consistency and review previous workflow executions.
Common Use Cases:
- ▸
Standup report generation: Aggregates ticket tracker, GitHub activity, and Slack history to generate formatted standup reports showing only changes - ▸
Ticket creation: Enforces field specifications (valid enum values, required fields) and post-creation workflows (notify reviewer, link in Slack) - ▸
Weekly recap: Merges merged PRs, closed tickets, and deployments into a formatted summary report
5. Code Scaffolding and Template Skills
These Skills generate framework boilerplate for specific functions in your codebase. You can combine them with composable scripts. They are especially useful when your scaffolding includes natural language requirements that cannot be fully expressed through code alone.
Application Scenarios:
- ▸
New workflow scaffolding: Creates new services, workflows, or handlers using your team’s annotations - ▸
Migration file templates: Includes your team’s migration file template and common pitfalls - ▸
Application creation: New internal applications with pre-configured authentication, logging, and deployment settings
6. Code Quality and Review Skills
These Skills enforce code quality standards within your organization and assist with code review. They can include deterministic scripts or tools for maximum robustness. You may want to run these Skills automatically as part of hooks or within GitHub Actions.
Feature Examples:
- ▸
Adversarial review: Spawns a “fresh eyes” subagent to critique code, implements fixes, and iterates until issues degrade to minor nitpicks - ▸
Code style: Enforces code styles, particularly those where Claude performs poorly by default - ▸
Testing practices: Guidance on how to write tests and what to test
7. CI/CD and Deployment Skills
These Skills assist with fetching, pushing, and deploying code within your codebase. These Skills may reference other Skills to collect data.
Real-world Cases:
- ▸
PR monitoring: Monitors PR → retries flaky CI → resolves merge conflicts → enables auto-merge - ▸
Service deployment: Build → smoke test → gradual traffic rollout with error rate comparison → auto-rollback on regression detection - ▸
Production cherry-pick: Isolated worktree → cherry-pick → conflict resolution → PR creation with template
8. Runbook Skills
These Skills take a symptom (such as a Slack thread, alert, or error signature), perform multi-tool investigations, and produce structured reports.
Typical Scenarios:
- ▸
Service debugging: Maps symptoms to tools and query patterns for high-traffic services - ▸
On-call runner: Fetches alerts → checks common causes → formats findings - ▸
Log correlator: Given a request ID, pulls matching logs from every system that might have processed it
9. Infrastructure Operations Skills
These Skills perform routine maintenance and operational procedures, some of which involve destructive actions that benefit from guardrails. They make it easier for engineers to follow best practices during critical operations.
Application Examples:
- ▸
Resource orphan cleanup: Finds orphaned pods/volumes → posts to Slack → soak period → user confirmation → cascading cleanup - ▸
Dependency management: Your organization’s dependency approval workflow - ▸
Cost investigation: “Why did our storage/egress bill spike?” with specific buckets and query patterns
Practical Techniques for Creating High-Quality Skills
Once you have determined the type of Skill to create, how do you write it to ensure it works effectively? Here are the best practices summarized by the Anthropic team.
Avoid Stating the Obvious
Claude Code already knows a great deal about your codebase, and Claude itself possesses extensive programming knowledge, including many default opinions. If you are writing a Skill primarily focused on knowledge, concentrate on information that pushes Claude out of its normal mode of thinking.
The Anthropic design system Skill serves as an excellent example. It was created by an engineer through iterative improvement of Claude’s design taste with customers, successfully avoiding common patterns like Inter font and purple gradients.
Build a Gotchas Section
The highest-value content in any Skill is the Gotchas section. These sections should be built from common failure points Claude encounters when using your Skill. Ideally, you will update your Skill over time to capture these pitfalls.
Use the File System and Progressive Disclosure
As mentioned earlier, a Skill is a folder, not just a Markdown file. You should treat the entire file system as a form of context engineering and progressive disclosure. Tell Claude what files are in your Skill, and it will read them at appropriate times.
The simplest form of progressive disclosure is pointing to other Markdown files for Claude to use. For example, you might split detailed function signatures and usage examples into references/api.md.
Another example: if your final output is a Markdown file, you might include a template file for it in assets/ to copy and use.
You can have folders of references, scripts, examples, and more, which help Claude work more effectively.
Avoid Railroading Claude
Claude will generally try to follow your instructions, and because Skills are so reusable, you need to be careful not to be too specific in your instructions. Give Claude the information it needs, but give it the flexibility to adapt to the situation.
Think Through the Setup
Some Skills may need to be set up with context from the user. For example, if you are making a Skill that posts your standup to Slack, you may want Claude to ask which Slack channel to post it in.
A good pattern for this is to store this setup information in a config.json file in the Skill directory. If the config is not set up, the agent can then ask the user for information.
If you want the agent to present structured, multiple-choice questions, you can instruct Claude to use the AskUserQuestion tool.
The Description Field Is for the Model
When Claude Code starts a session, it builds a listing of every available Skill with its description. This listing is what Claude scans to decide “is there a Skill for this request?” This means the description field is not a summary—it is a description of when to trigger this Skill.
Memory and Data Storage
Some Skills can include a form of memory by storing data within them. You could store data in anything as simple as an append-only text log file or JSON files, or as complicated as a SQLite database.
For example, a standup-post Skill might keep a standups.log with every post it has written, which means the next time you run it, Claude reads its own history and can tell what has changed since yesterday.
Data stored in the Skill directory may be deleted when you upgrade the Skill, so you should store this in a stable folder. Anthropic provides ${CLAUDE_PLUGIN_DATA} as a stable folder per plugin to store data in.
Store Scripts and Generate Code
One of the most powerful tools you can give Claude is code. Giving Claude scripts and libraries lets Claude spend its turns on composition—deciding what to do next—rather than reconstructing boilerplate.
For example, in your data science Skill, you might have a library of functions to fetch data from your event source. To enable Claude to perform complex analysis, you could give it a set of helper functions. Claude can then generate scripts on the fly to compose this functionality for prompts like “What happened on Tuesday?”
On-Demand Hooks
Skills can include hooks that are only activated when the Skill is called, and last for the duration of the session. Use this for more opinionated hooks that you do not want to run all the time, but are extremely useful sometimes.
Examples:
- ▸
/careful: Blocksrm -rf,DROP TABLE, force-push,kubectl deletevia PreToolUse matcher on Bash. You only want this when you know you are touching production—having it always on would be frustrating - ▸
/freeze: Blocks any Edit/Write that is not in a specific directory. Useful when debugging: “I want to add logs but I keep accidentally ‘fixing’ unrelated code”
Distributing and Sharing Skills
One of the biggest benefits of Skills is that you can share them with the rest of your team.
Two Distribution Methods
Method One: Check into Your Repository
Check your Skills into your repository (under ./.claude/skills). For smaller teams working across relatively few repositories, this works well. But every Skill that is checked in also adds a little bit to the context of the model.
Method Two: Plugin Marketplace
Create a plugin and establish a Claude Code Plugin marketplace where users can upload and install plugins. As you scale, an internal plugin marketplace allows you to distribute Skills and let your team decide which ones to install.
Managing a Marketplace
How do you decide which Skills go into a marketplace? How do people submit them?
Anthropic does not have a centralized team that decides; instead, they try to find the most useful Skills organically. If you have a Skill that you want people to try out, you can upload it to a sandbox folder in GitHub and point people to it in Slack or other forums.
Once a Skill has gained traction (which is up to the Skill owner to decide), they can put in a PR to move it into the marketplace.
It is worth noting that it can be quite easy to create bad or redundant Skills, so ensuring you have some method of curation before release is important.
Composing Skills
You may want to have Skills that depend on each other. For example, you might have a file upload Skill that uploads a file, and a CSV generation Skill that makes a CSV and uploads it. This sort of dependency management is not natively built into marketplaces or Skills yet, but you can reference other Skills by name, and the model will invoke them if they are installed.
Measuring Skills
To understand how a Skill is performing, you can use a PreToolUse hook to log Skill usage within your organization. This means you can find Skills that are popular or are under-triggering compared to your expectations.
Frequently Asked Questions
Q: What is the difference between Skills and regular Claude prompts?
Skills are structured, reusable knowledge packages. Unlike one-off prompts, Skills can contain scripts, configuration files, templates, and progressively loaded reference documentation. They can also deeply integrate with Claude Code’s runtime behavior through hooks.
Q: Where should my team start creating Skills?
Start with your most painful repetitive tasks. Review the nine types listed above and identify scenarios where your team frequently encounters friction in daily work. Typically, internal API documentation, code review standards, or deployment processes are good starting points.
Q: Can a Skill span multiple types?
While some Skills may cross multiple categories, the Anthropic team has found that the best Skills usually fit cleanly into a single category. Skills that span multiple types tend to confuse users.
Q: How do I prevent a Skill from being triggered incorrectly?
Write the description field carefully. This field is not a summary for humans—it tells Claude under what circumstances it should activate this Skill. Use specific trigger condition descriptions, including keywords related to file types, actions, and tools.
Q: What is the relationship between Skills and MCP Servers?
Both Skills and MCP (Model Context Protocol) Servers are ways to extend Claude’s capabilities, but they serve different layers. Skills are typically lightweight knowledge packages within Claude Code, while MCP Servers are independently running external services. Some Skills may call MCP Servers to complete tasks.
Q: How do I update and maintain Skills?
Skills should be living documents. When Claude encounters new edge cases or error patterns while using a Skill, update the Gotchas section promptly. For Skills checked into repositories, use normal code review processes; for Skills in the plugin marketplace, follow your team’s release process.
Q: How are Skills distributed for private repositories?
Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers. If git clone works for a private repository in your terminal, it works in Claude Code. For automatic updates, you need to set appropriate authentication tokens in your environment, such as GITHUB_TOKEN or GH_TOKEN.
Conclusion
Skills are powerful and flexible tools for agents, but this is still an emerging field, and we are all figuring out how to use them best.
What this article provides is more of a collection of practical tips that the Anthropic team has validated, rather than a definitive guide. The best way to understand Skills is to start practicing, experiment, and see what works for you. Most of Anthropic’s Skills began as a few lines of code and a single gotcha, and improved because people kept adding to them as Claude hit new edge cases.
We hope these lessons from a frontline development team will help you use Claude Code Skills more efficiently and build workflows that suit your team.
This article is based on the practical experience of the Anthropic engineering team using Skills in Claude Code, covering the complete knowledge system from Skill categorization, creation techniques, to distribution management.
