Anthropic shares lessons from scaling Claude Code skills

Anthropic has published lessons from building and scaling hundreds of internal skills for Claude Code, its coding assistant. The post says skills are now one of Claude Code’s most used extension points because they are flexible, easy to build, and easy to share.

The company defines skills as folders of instructions, scripts, and resources that agents can discover and use to work more accurately and efficiently. Anthropic also says a skill is more than a markdown file: it can include code, assets, data, configuration, and dynamic hooks.

The post assumes readers already know the basics of skills and points new users to Anthropic’s Introduction to agent skills course on Skilljar. It also links to the documentation for more detail.

After cataloging internal skills, Anthropic says it found nine broad categories. These include skills for using libraries, command-line tools, and SDKs; skills for testing and verification; skills for data and monitoring; and skills that automate repetitive workflows.

Other categories cover scaffolding new framework boilerplates, enforcing code quality, helping with fetch/push/deploy flows, debugging symptoms across tools, and handling maintenance or operational procedures. Anthropic says the best skills fit cleanly into one category, while skills that try to do too much tend to confuse the agent.

The company says verification skills have had the most measurable impact on output quality. These are skills that test whether code works, often by using tools such as Playwright, tmux, or scripts that assert state at each step.

Anthropic gives examples such as signup-flow-driver, checkout-verifier, and tmux-cli-driver. It says it can be worth having an engineer spend a week making verification skills excellent.

The post says the highest-signal content in a skill is the Gotchas section. Anthropic says these should capture common failure points, such as append-only tables, mismatched field names across systems, or tests that return false confidence.

It also says skills should use progressive disclosure. In practice, that means a skill is a folder with references, scripts, examples, and other files that Claude reads as needed, instead of forcing everything into one file.

Anthropic recommends giving Claude enough information to be useful, but not so much that the instructions become overly specific. The company says some skills should ask the user for setup details, and that config files can store that information when it is available.

The post notes that Claude Code builds a listing of all available skills at the start of a session, and that the description field should explain when a skill should trigger, not summarize the whole thing. It also says skills can store memory in text logs, JSON, or SQLite, and that the environment variable ${CLAUDE_PLUGIN_DATA} provides a stable place to keep persistent data.

Anthropic says one of the biggest advantages of skills is that they can be shared. Teams can check skills into a repo under ./.claude/skills, or distribute them through a Claude Code Plugin marketplace. For smaller teams, repo-based sharing works well, while larger organizations may prefer a marketplace.

The company says it does not use a central team to approve every skill. Instead, useful skills spread organically, often first through a sandbox GitHub folder and Slack before being moved into the marketplace after they gain traction.

To measure what is working, Anthropic says it uses a PreToolUse hook to log skill usage internally. That lets the company see which skills are popular and which are underused.

The post closes by saying skills are still evolving and that many of Anthropic’s best ones started as a few lines and a single gotcha before being improved over time.