Anthropic's internal playbook for Claude Code skills
Anthropic published a field report on how it uses Claude Code skills internally, sorting hundreds of them into nine categories and laying out the patterns that actually hold up in production.
Builders, integrators, prompt engineers · 2 min read
Anthropic's Claude Code team has put out what is essentially an internal best-practices doc for skills — the folders of instructions, scripts, and assets that agents discover and use to do work more reliably. The post claims hundreds of skills in active use internally, and the receipts come in the form of a taxonomy and a tips section, not benchmarks.
A few things worth pulling out for anyone actually building on Claude Code.
Skills are folders, not markdown files. Anthropic is pushing back on the common framing that a skill is a single SKILL.md. In their telling, the file system itself is the context-engineering tool: references/api.md for detailed signatures, assets/ for templates, scripts for verification, JSON or SQLite for memory. The SKILL.md is the entry point that tells Claude what else is in the folder and when to read it — progressive disclosure as a design pattern.
The nine categories. Anthropic groups its internal skills into: library/API reference, product verification, data fetching and analysis, business process automation, code scaffolding, code quality and review, CI/CD and deployment, runbooks, and infrastructure operations. The argument is that good skills sit cleanly in one bucket; skills that straddle several confuse the agent. It's a useful audit framework if you're building a skill library and want to see where the holes are.
Verification is where the leverage is. The most pointed claim in the post: verification skills have had "the most measurable impact on Claude's output quality internally," and they say it's worth a week of an engineer's time to make yours excellent. Their examples lean on Playwright, tmux for TTY-bound CLIs, Stripe test cards, and — notably — having Claude record video of what it tested so a human can audit. Programmatic state assertions at each step are recommended over vibes-based passing.
Descriptions are routing metadata, not docs. When a session starts, Claude scans every skill's description to decide which to invoke. So the description field should read like a trigger list ("babysit," "flaky CI," etc.), not a human-readable summary. This is a small detail that will quietly determine whether your skill ever fires.
Other patterns worth stealing: a Gotchas section as the highest-signal part of any skill ("the subscriptions table is append-only — take the highest version, not the latest created_at"); a config.json in the skill directory where Claude can ask the user for setup info on first run; append-only log files or JSON memory via ${CLAUDE_PLUGIN_DATA} so a skill like standup-post can read its own history; and an explicit warning against railroading — give Claude the information, not a rigid script.
The honest read: this isn't new product, it's Anthropic codifying conventions for an extension surface they clearly want third-party developers to build on. The taxonomy is the most reusable artifact here. If your team is shipping agents and hasn't audited which of those nine buckets you've covered, that's the exercise.
