Anthropic’s Internal Claude Code Skills: 9 Categories, Best Practices, and Lessons Learned

Understanding Claude Code Skills

Anthropic clarifies a common misconception: a Skill is not just a few prompt lines but a folder‑like bundle of files that supplies the model with everything it needs to complete a task, including SKILL.md, reference documents, scripts, templates, hooks, and even data that later steps may read.

9 Functional Categories

The internal audit groups Skills into nine categories that together form a full software workflow, from knowledge enrichment to production deployment:

First three (knowledge, verification, data) : library/API reference, product verification (running end‑to‑end flows in a headless browser), and data fetching/analysis.

Middle three (team processes) : business process automation, code scaffolding/templates, and code quality/review (e.g., adversarial-review).

Last three (production) : CI/CD and deployment (e.g., babysit-pr, deploy-<service>), runbooks that map symptoms to tools, and infrastructure operations with guardrails.

Why Verification Is Critical

Anthropic stresses that verification Skills provide the biggest quality boost because models often give the illusion of completion. Engineers are encouraged to spend a dedicated week polishing verification Skills, record test videos, and add programmatic assertions to confirm state changes, database writes, or external service outcomes.

Writing Effective Skills – Five Practical Tips

Don’t repeat obvious information. Skills should surface details the model cannot infer, such as team‑specific design tastes or gotchas.

Use SKILL.md as a directory, not a catch‑all. Split reference material into separate files (e.g., stuck-jobs.md, references/api.md) and keep templates in an assets/ folder.

Leave flexibility. Provide key rules but allow the model to adapt; otherwise a Skill may break when reused in a different context.

Plan the setup ahead. Store required user context in config.json and fall back to AskUserQuestion when missing.

Write descriptions for the model. The description is the trigger condition, not a human‑readable summary. Include keywords, expected file uploads, and scenarios that should activate the Skill (e.g., the word “babysit”).

Beyond the Core – Memory, Scripts, and Hooks

When a Skill is used repeatedly, three extensions emerge:

Memory. Log outputs (e.g., standup-post → standups.log) and read them on the next run. Storage can be simple append‑only text, JSON, SQLite, or the ${CLAUDE_PLUGIN_DATA} directory.

Scripts. Pre‑bundle data‑fetching or analysis functions so Claude spends more rounds on orchestration rather than rewriting boilerplate.

On‑demand hooks. High‑risk commands ( rm -rf, DROP TABLE, kubectl delete) are wrapped in protective hooks (e.g., /careful, /freeze) that block accidental destructive actions.

Distribution and Governance at Scale

As Skills spread, two distribution models appear:

Check‑in Skills to a repository under /.claude/skills for small teams.

Publish them as plugins in the internal Claude Code Plugin Marketplace for larger organizations, reducing context load and letting users install independently.

Governance remains lightweight: contributors push a sandbox version to GitHub, share it via Slack, and once it gains traction, the owner submits a PR to the marketplace. Usage is tracked with PreToolUse hooks to identify popular versus under‑used Skills.

Composition and Measurement

Skills can call one another (e.g., a file‑upload Skill invoked after a CSV‑generation Skill). Although not a native marketplace feature, naming another Skill in the code enables composition when both are installed. Usage metrics help surface which Skills need better descriptions or guardrails.

Final Takeaways

The most effective Skills start as a few lines and a gotcha, then evolve with verification, memory, scripts, and distribution. Teams are encouraged to begin with the most repetitive task, write concise, focused documentation, and let real usage drive further refinement.

Original link: https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills