# The Nine Types of Claude Code Skills: From Personal Prompts to Org-Level Agent Capability
Anthropic's internal experience with hundreds of skills shows: a skill is not a Markdown prompt, it's an explorable capability package — verification skills should come before code-generation skills.
In June 2026, Anthropic summarized the Claude Code team’s experience scaling to hundreds of skills. The key insight isn’t “how to write better Markdown” — it’s that skills are a combination of org-facing knowledge, executable scripts, verification workflows, context distribution, and governance mechanisms for agents.
In one sentence: Skills are the critical middle layer between “personal prompting tricks” and “org-level Agent Enablement.”
What a Skill Really Is: A Capability Package, Not a Single File
In Claude Code, a skill is a directory:
| Component | Role |
|---|---|
SKILL.md | Entry point, trigger conditions, execution steps |
references/ | API docs, internal conventions, edge cases |
scripts/ | Validators, data fetchers, generators |
assets/ | Templates, report skeletons |
config.json | Team/environment configuration |
| hooks | Safety constraints enabled on demand |
The design focus isn’t “write a complete description” — it’s exposing context on demand. SKILL.md handles navigation; details unfold via filesystem-based progressive disclosure.
Anthropic’s Nine Types
| # | Type | Problem it solves | AI4SE meaning |
|---|---|---|---|
| 1 | Library & API reference | Internal library/CLI/SDK usage and pitfalls | Captures senior engineers’ tacit API knowledge |
| 2 | Product verification | How to verify code actually works | Top priority; improves acceptance trustworthiness |
| 3 | Data fetching & analysis | Connecting to monitoring/analytics stacks | Moves the agent from writing code into a “look at the facts” loop |
| 4 | Business process automation | Standups, tickets, weekly reports | One-click team processes |
| 5 | Code scaffolding | Generating framework code per org convention | Scaffolding for cases natural-language conditions + templates can’t cover |
| 6 | Code quality & review | Org-level review rules | Moves review standards upstream into agent execution |
| 7 | CI/CD & deployment | Build, release, PR babysitting | Bridges the Inner Loop and the Outer Loop |
| 8 | Runbooks | Multi-tool troubleshooting from symptoms | Structures operational experience |
| 9 | Infrastructure ops | Routine infra and high-risk maintenance | Pairs with hooks to handle destructive operations |
The most important observation: verification-type skills have the most measurable impact on output quality. What organizations care about isn’t “how much code the AI wrote,” but whether the code actually runs, whether state is consistent, and whether the agent can prove — in a repeatable way — that it completed the task.
Design Principles
Gotchas Are the Highest-Signal Content
Don’t write down what Claude already knows. High-value skills focus on:
- Special conventions of internal systems
- Fields, state machines, and permission boundaries that are easy to get wrong
- Workflows that can only be verified with a specific tool/environment
Example: some table is append-only, so you can’t grab the “latest” row by created_at; a 200 in staging doesn’t mean the webhook was actually processed.
Description Is a Trigger, Not a Summary
Claude Code scans skill descriptions at startup to decide whether to invoke one. It should include: explicit trigger words, applicable task types, boundaries where it doesn’t apply, and natural-language phrasings a user might actually use.
Provide Constraints, but Also Flexibility
Avoid railroading: clearly state when it should/shouldn’t trigger, success criteria, optional paths, and fallbacks — don’t bake the context of a single task into a permanent rule.
On-Demand Hooks Fit High-Constraint Scenarios
Blocking DROP TABLE or force-push in production; enforcing smoke tests during a release window — temporarily raising the safety bar within a specific workflow, rather than a global hard constraint.
Distribution and Governance
| Approach | Fits | Pros | Risks |
|---|---|---|---|
./.claude/skills (in-repo) | Small teams, tightly project-bound | Fast to adopt, versioned with code | Context noise grows as it scales |
| Internal plugin marketplace | Multi-team, multi-repo | Install on demand, governable | Needs admission and lifecycle management |
Recommended path: pilot in-repo first, then build a marketplace once skill count and reuse scope grow.
Anthropic’s lightweight governance: sandbox → Slack trial → traction → PR into marketplace — organic discovery rather than a centralized approval bottleneck.
Where Skills Sit in AI4SE
Skills fit best in the Middle Loop (review, verification, collaboration, process):
- Turn team working methods into agent-executable steps
- Move verification and review standards earlier in the development process
- Migrate gotchas from individual heads into organizational assets
Relationship to Harness Engineering: Harness defines the five-dimension control over the agent’s operating environment; Skills are the reusable, distributable, measurable implementation of the Context dimension.
Pilot Priority Order
Don’t start by building an “all-purpose dev skill.” Suggested order:
- Verification skills for key business processes
- Reference skills for internal libraries/APIs
- Code review / testing practices skills
- CI/CD babysitting or deployment skills
- Business process automation skills
The skill library should be driven by real failures: collect AI failure samples → extract recurring gotchas → script the verification → pilot a small skill → observe trigger rate → then expand.
Measurable Metrics
| Metric | Meaning |
|---|---|
| Skill trigger count | Which processes have been agentified |
| Share of verification-skill usage | Whether the shift is from “generation-first” to “verification-first” |
| Growth in gotchas | Whether org knowledge keeps accumulating |
| Skill-related rework rate | Whether review/QA rework is actually reduced |
References
- Thariq Shihipar, Lessons from building Claude Code: How we use skills, Anthropic, 2026-06-03