How Anthropic Uses Claude Code Skills Internally

Practical advice on Skills from Anthropic Claude Code engineer Thariq Shihipar, covering nine recurring Skill categories, writing techniques such as pitfalls, progressive disclosure, and on-demand hooks, plus distribution and marketplace management.

The author, Thariq Shihipar (@trq212), is an engineer on Anthropic's Claude Code team and one of the people driving the Skills feature. Before joining Anthropic, he co-founded the open-source academic publishing platform PubPub while studying at the MIT Media Lab, then joined Y Combinator's W20 batch. He regularly shares first-hand Claude Code experience and feature updates on X.

The article is valuable because it distills real experience from Anthropic's internal teams. Anthropic actively uses hundreds of Skills, and the categories and writing techniques below come from those actual practices.

If you already use Claude Code but have not seriously built Skills, this article provides a systematic framework: what kinds of Skills to create, how to write them, and how to promote them within a team.

Background

Skills are among Claude Code's most widely used extension points: they are flexible, easy to create, and easy to distribute. That flexibility also makes it difficult to decide which Skills are worth building, how to write them well, and when to share them. Anthropic currently has hundreds of Skills in active internal use.

A common misconception: Many people think a Skill is merely a Markdown file. In reality, a Skill is a folder that may contain scripts, resources, data, and more. An agent can proactively discover, explore, and use this content. Claude Code Skills also support rich configuration, including dynamic hook registration.

1. Nine Common Types of Skills

After reviewing all internal Skills, nine recurring categories emerged. A good Skill usually belongs clearly to one category; confusing Skills often span several.

1. Library and API References

These help Claude use a library, CLI, or SDK correctly. They can target internal libraries or common libraries that Claude tends to misuse. They usually combine reference snippets with a list of pitfalls.

• Examples: edge-case notes for an internal billing library; usage for every subcommand of an internal CLI; frontend-design, which helps Claude understand a team's design system.

  The third example in the official blog is sandbox-proxy, which explains how to configure an organization's outbound gateway: which hosts are reachable, how to troubleshoot “connection refused,” and how to add allowlist entries.

2. Product Verification

These explain how to test or verify that code works, often with external tools such as Playwright and tmux. They can be worth a full week of focused refinement. Useful techniques include asking Claude to record a video for reviewing the test process and requiring programmatic state assertions at every step.

• Examples: complete the sign-up → email verification → onboarding flow with assertions at each step; use test cards to exercise checkout UI and verify invoice state; test interactive command-line tools that require a TTY.

3. Data Retrieval and Analysis

These connect data and observability systems. They may include credential-aware data libraries, dashboard IDs, and descriptions of common workflows.

• Examples: which event tables to join for a conversion-funnel query; compare retention or conversion between two user cohorts and flag statistical significance; map Grafana data-source UIDs to troubleshooting guidance.

4. Business Processes and Team Automation

These compress repetitive workflows into a single command. Their instructions are often simple and may depend on other Skills or MCP. Saving historical results in a log helps the model remain consistent.

• Examples: combine task-system activity, GitHub activity, and historical Slack messages into a stand-up report that only mentions changes; validate required fields when creating a ticket and notify reviewers automatically; produce a weekly report from merged PRs, closed tickets, and deployment records.

5. Code Scaffolding and Templates

These generate boilerplate for a specific feature in a codebase and work well with scripts. They are especially useful when scaffolding requires natural-language judgment that pure code cannot cover.

• Examples: scaffold a new service or workflow from annotations; provide a database-migration template plus common pitfalls; create an internal application preconfigured with authentication, logging, and deployment.

6. Code Quality and Review

These enforce code-quality standards and assist reviews. They may include deterministic scripts for reliability and can run automatically as hooks or through GitHub Actions.

• Examples: ask a fresh subagent to challenge the implementation, then fix and repeat, avoiding the original instance's mental inertia; enforce style rules Claude commonly overlooks; provide guidance for writing tests.

7. CI/CD and Deployment

These help pull, push, and deploy code, and may reference other Skills to collect information.

• Examples: monitor a PR, retry flaky CI, resolve merge conflicts, and enable auto-merge; build → smoke-test → gradually shift traffic while comparing error rates, rolling back automatically on anomalies; cherry-pick in an isolated worktree and create a PR from a template.

8. Runbooks

These accept a symptom—an alert, error signature, or Slack message—guide a multi-tool investigation, and produce a structured report.

• Examples: map symptoms to tool-query patterns for the highest-traffic services; retrieve alerts, inspect common suspects, and format the findings; given a request ID, collect matching logs across systems.

9. Infrastructure Operations

These perform routine maintenance and operational work. Some involve destructive actions and require safety guardrails, helping engineers follow best practices during critical operations.

• Examples: find orphaned Pods or Volumes → notify Slack → wait → request user confirmation → cascade-delete; manage an internal dependency-approval workflow; investigate sudden increases in storage or outbound-bandwidth costs.

2. Techniques for Writing Skills

1. Do Not State the Obvious

Claude already understands a codebase well and has strong programming ability, including many sound defaults. If a Skill primarily conveys knowledge, focus on information that changes Claude's usual reasoning pattern instead of repeating common knowledge.

Example: Anthropic's frontend-design Skill encodes “design taste” refined over many iterations and specifically avoids familiar AI clichés such as Inter everywhere and purple gradients.

2. Add a “Pitfalls” Section

This is often the most information-dense part of a Skill. Keep adding and updating real failure cases discovered while Claude uses it.

3. Use the File System and Progressive Disclosure

A Skill is a folder, not a single file. Treat its file system as a context-engineering tool:

• Tell Claude which files are available so it can read them when needed.
• Move detailed function signatures and usage examples into files such as references/api.md.
• If the final output is Markdown, put a reusable template in assets/.

4. Do Not Over-Constrain Claude

Skills are highly reusable, but overly specific instructions make them inflexible. Give Claude enough information while leaving room to adapt to the current situation.

5. Plan the Initial Setup

Some Skills require user context during setup—for example, a stand-up bot needs to know which Slack channel to use. Store setup information in config.json inside the Skill directory. If configuration is missing, have the agent ask for it. Use AskUserQuestion when a structured multiple-choice prompt is helpful.

6. The description Is for the Model, Not a Summary

At the start of a session, Claude Code scans every Skill description to decide whether a request should trigger it. A description should therefore explain when to trigger the Skill rather than merely what it does; it should read more like an if-then condition.

7. Memory and Data Storage

A Skill can implement “memory” by storing data internally:

• Simple option: an append-only text log or JSON file.
• More advanced option: a SQLite database.
• Example: a stand-up Skill keeps standups.log and reads it on the next run to determine what changed since yesterday.
• Important: Data inside a Skill directory may be cleared when the Skill is upgraded. Store it in a stable location instead. Anthropic provides ${CLAUDE_PLUGIN_DATA} as stable, per-plugin storage.

8. Store Scripts and Generated Code

Provide scripts and function libraries so Claude can focus on orchestration—deciding what to do next—instead of rewriting boilerplate. A data-science Skill, for example, can provide data-retrieval helpers that Claude composes on demand to answer questions such as “What happened on Tuesday?”

9. On-Demand Hooks

A Skill can contain hooks that activate only when the Skill is invoked and remain active for the rest of the session. This works well for subjective or occasional behavior that should not always be enabled.

• /careful: uses PreToolUse to intercept dangerous commands such as rm -rf, DROP TABLE, force-push, and kubectl delete; enable it only for explicit production work.
• /freeze: blocks Edit and Write outside specified directories, preventing unrelated changes during debugging.

3. Distributing Skills

There are two ways to share Skills:

1. Commit them to a repository under ./.claude/skills. This is straightforward and works well for small teams collaborating across a few repositories.
2. Package them as plugins and host a Plugin Marketplace. As usage grows, every committed Skill consumes model context. A marketplace lets team members choose which ones to install. The official blog also notes that a marketplace can include an installation and configuration flow.

Managing a Plugin Marketplace

Anthropic has no dedicated central review team. It prefers useful Skills to emerge organically:

• First upload a Skill to a sandbox folder on GitHub and recommend it in Slack or a forum.
• Once it attracts enough interest—as judged by its author—open a PR to move it into the official marketplace.
• Be aware that low-quality and duplicate Skills are easy to create, so some review mechanism is still necessary before publication.

Composing Skills

Skills may depend on one another—for example, a file-upload Skill and a CSV-generation Skill. The marketplace and Skill mechanism do not currently provide formal dependency management, but one Skill can reference another by name. If the other Skill is installed, the model will invoke it automatically.

Measuring Skill Effectiveness

Use a PreToolUse hook to record Skill usage internally. The original article includes an example gist. This reveals which Skills are popular and which trigger less often than expected.

Key Takeaways

• Skills are still early, and best practices continue to evolve.
• This article is a collection of techniques proven useful in practice, not an authoritative guide.
• The best way to understand Skills is to build and experiment with them.
• Most Skills start simply—a few lines of text and one pitfall—and grow as a team adds edge cases.

These notes organize and summarize the source rather than translate it word for word. For the complete original, including images, see:

• Original thread: https://x.com/trq212/status/2033949937936085378
• Revised Anthropic blog post: https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills