Anthropic’s Internal Claude Code Skills: 9 Types, Key Practices, and Writing Tips

Skill definition

A Claude Code Skill is a directory that bundles all artefacts required for a task: a SKILL.md manifest, reference documentation, scripts, templates, example files, and optional persistent data. When Claude invokes a Skill it receives the entire directory as context.

9 Skill categories

First three – knowledge, verification, data

Library / API reference – files that explain internal SDKs, CLIs or library usage and enumerate common pitfalls (e.g., field‑name mismatches such as @request_id vs trace_id).

Product verification – end‑to‑end headless‑browser flows that confirm a feature actually works (e.g., registration + checkout). Anthropic notes that verification yields the biggest quality lift and recommends dedicating a week to perfect these Skills.

Data fetching & analysis – stored queries, field conventions, and analysis pipelines that hide schema details from the model (e.g., “subscriptions” table is append‑only, use the highest version not just the latest created_at).

Middle three – team processes

Business process automation – repeatable workflows such as generating a stand‑up diff or a weekly report.

Code scaffolding & templates – skeletons for new services or migration files that embed domain‑specific constraints beyond pure templating.

Code quality & review – sub‑agents like adversarial‑review that inject a fresh perspective into PR checks; can be wired as CI hooks.

Last three – production

CI/CD & deployment – Skills such as babysit‑pr (monitor a PR lifecycle) and deploy‑<service> (build, traffic shift, error‑rate comparison, rollback).

Runbooks – symptom‑driven entry points that map alerts, request IDs, or Slack threads to diagnostic tools and produce structured conclusions.

Infrastructure operations – guarded actions for resource cleanup, dependency governance, or cost checks; include explicit guardrails (notify → confirm → execute).

Core design principles

Focus – narrow scope keeps the model from being confused; a Skill that fits cleanly into one of the nine categories is more stable.

Verification – the final step must be observable; models can falsely report completion, so engineers should record test videos and add programmatic assertions (state change, DB write, final page URL).

Gotchas – team‑specific pitfalls (append‑only tables, field‑name differences, Stripe webhook status) provide the highest‑signal content and should be highlighted.

How to write effective Skills

Avoid repeating information the model already knows; include only material the model cannot infer.

Make SKILL.md a high‑level index. Place detailed files (e.g., stuck‑jobs.md, references/api.md, assets/ templates) alongside the manifest so the top‑level stays concise.

Do not hard‑code every path; leave flexibility for the model to adapt to variations in context.

Declare required user context in config.json. If a value is missing, fall back to the AskUserQuestion tool for interactive prompting.

Write the description as a trigger clause: list keywords, file types, and scenarios that should activate the Skill (e.g., include the word “babysit” to match babysit‑pr).

Progressive extensions

Memory – append‑only logs (e.g., standups.log) or SQLite databases stored under the ${CLAUDE_PLUGIN_DATA} directory. A Skill can read its own history to compute deltas (e.g., compare today’s stand‑up to yesterday’s).

Scripts – pre‑written data‑fetching or analysis functions. By shipping helper functions, Claude spends more rounds on orchestration than on boilerplate code (e.g., a CSV‑generation script that the model composes with a file‑upload Skill).

Hooks – on‑demand safety checks that block dangerous commands ( /careful rm -rf, /freeze) or enforce guardrails before destructive operations (e.g., prevent DROP TABLE unless explicitly allowed).

Distribution and governance

For small teams, Skills are checked into the repository under ./.claude/skills. Larger organisations can publish them to the internal Claude Code Plugin marketplace. The workflow is lightweight: place a Skill in a sandbox folder, share a Slack link for trial, then promote via a PR to the marketplace.

Skills can reference one another (e.g., a CSV‑generation Skill calls a file‑upload Skill). Usage is tracked with the PreToolUse hook, enabling teams to see which Skills are popular and where activation gaps exist.

Takeaway

The most reliable Skills start as a few lines plus a single gotcha, then evolve through focused verification, progressive disclosure (directory‑style SKILL.md), and the addition of memory, scripts, and hooks. Teams should begin with their highest‑frequency repetitive task, encode the essential gotchas, and let real‑world usage drive further enrichment.