# Anthropic Best Practices for Claude Code Skills

This reference summarizes the key lessons from Anthropic's internal skill usage (hundreds of skills in active use). Use this as the grading rubric when reviewing skills.

## Skill Categories (Anthropic taxonomy)

A well-designed skill fits cleanly into **one** category. Straddling multiple is a smell.

| # | Category | Purpose | Examples |
|---|----------|---------|----------|
| 1 | **Library & API Reference** | How to correctly use a library, CLI, or SDK. Gotchas, edge cases, reference snippets. | billing-lib, internal-platform-cli, frontend-design |
| 2 | **Product Verification** | Test or verify that code works. Often paired with playwright, tmux, etc. | signup-flow-driver, checkout-verifier |
| 3 | **Data Fetching & Analysis** | Connect to data/monitoring stacks. Credentials, dashboard IDs, common workflows. | funnel-query, cohort-compare, grafana |
| 4 | **Business Process & Automation** | Automate repetitive workflows into one command. | standup-post, create-ticket, weekly-recap |
| 5 | **Code Scaffolding & Templates** | Generate boilerplate for a specific function in codebase. | new-workflow, new-migration, create-app |
| 6 | **Code Quality & Review** | Enforce code quality, review code. May include deterministic scripts. | adversarial-review, code-style, testing-practices |
| 7 | **CI/CD & Deployment** | Fetch, push, deploy code. May reference other skills for data. | babysit-pr, deploy-service, cherry-pick-prod |
| 8 | **Runbooks** | Take symptom → multi-tool investigation → structured report. | service-debugging, oncall-runner, log-correlator |
| 9 | **Infrastructure Operations** | Routine maintenance, operational procedures with guardrails. | resource-orphans, dependency-management, cost-investigation |

---

## The 15-Point Checklist

### Structure (1-5)

#### 1. Executable Scripts
> "Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate."

**Why it matters**: Scripts are deterministic — same input, same output, every time. They save tokens (no need to reconstruct logic) and reduce hallucination risk on mechanical tasks.

**What to look for**:
- `.sh`, `.py`, `.js` files in `scripts/` directory
- Scripts for repetitive operations (API calls, log parsing, formatting)
- Library functions Claude can compose rather than rebuild

**Scoring**:
- PASS: Has scripts that handle deterministic/mechanical subtasks
- PARTIAL: Has scripts but they're trivial or underutilized
- MISSING: 100% markdown, no executable code
- N/A: Skill is purely instructional (rare)

#### 2. Progressive Disclosure
> "Think of the entire file system as a form of context engineering and progressive disclosure."

**Why it matters**: Loading everything into SKILL.md wastes context on information not needed for every invocation. Reference files let Claude pull in detail only when relevant.

**What to look for**:
- `references/` directory with separate files
- SKILL.md explicitly points to reference files with guidance on when to read them
- Large tables, API specs, or domain data in reference files (not inline)

**Scoring**:
- PASS: References/ exists, SKILL.md points to files with clear "read this when..." guidance
- PARTIAL: References/ exists but SKILL.md doesn't explain when to read what
- MISSING: Everything in SKILL.md, or reference files exist but aren't referenced

#### 3. Gotchas Section
> "The highest-signal content in any skill is the Gotchas section."

**Why it matters**: Gotchas capture failure modes Claude hits repeatedly. They're the most cost-effective content — a single line can prevent a common 5-minute mistake.

**What to look for**:
- Explicit `## Gotchas` section (separate from Rules/Process)
- Built from real failure experience, not hypothetical
- Specific and actionable (not "be careful with X")

**Scoring**:
- PASS: Dedicated Gotchas section with concrete, experience-driven items
- PARTIAL: Gotchas mixed into Rules section, or present but generic
- MISSING: No gotchas documented

#### 4. File Count & Size
> "Keep SKILL.md under 500 lines; if approaching this limit, add hierarchy."

**Why it matters**: Long SKILL.md files get partially skimmed. Critical instructions at line 400 may be deprioritized. Reference files over 300 lines should have a table of contents.

**What to look for**:
- SKILL.md under 300 lines (ideal) or 500 (max)
- Reference files under 300 lines each, or with TOC if longer
- No single file trying to do everything

**Scoring**:
- PASS: SKILL.md < 300 lines, references well-scoped
- PARTIAL: SKILL.md 300-500 lines, or one oversized reference file
- MISSING: SKILL.md > 500 lines, or massive monolithic references

#### 5. Config Setup Pattern
> "Store setup information in a config.json file in the skill directory."

**Why it matters**: Hardcoded values (channel IDs, API endpoints, project IDs) break when the environment changes. A config file makes skills portable and user-configurable.

**What to look for**:
- `config.json` in skill directory
- Hardcoded IDs, URLs, or environment-specific values in SKILL.md
- Setup instructions that ask user for context on first run

**Scoring**:
- PASS: Config file exists, skill reads from it, SKILL.md references it
- PARTIAL: Some values configurable but others hardcoded
- MISSING: Environment-specific values hardcoded in SKILL.md
- N/A: Skill has no environment-specific configuration

### Description Quality (6-7)

#### 6. Description as Trigger Spec
> "The description field is not a summary — it's a description of when to trigger."

**Why it matters**: Claude scans descriptions to decide "is there a skill for this request?" If the description reads like a human README, Claude won't trigger it at the right times.

**What to look for**:
- Trigger phrases: "Use when the user says X, Y, Z"
- Multiple phrasings (French + English if applicable)
- Covers both explicit invocations and implicit triggers (user describes need without naming skill)

**Scoring**:
- PASS: Lists 3+ trigger phrases, covers explicit and implicit triggers
- PARTIAL: Has some trigger phrases but misses common phrasings
- MISSING: Description reads like a README summary

#### 7. Description Avoids Vagueness
> "Claude has a tendency to undertrigger skills"

**Why it matters**: Vague descriptions cause under-triggering (Claude doesn't realize the skill is relevant) or over-triggering (Claude uses it for unrelated requests). The description should be specific enough to have clear boundaries.

**What to look for**:
- Specific domain/context (not "helps with code")
- Clear boundaries (what this skill does NOT do)
- Slightly "pushy" to combat undertriggering

**Scoring**:
- PASS: Specific, bounded, with clear trigger conditions
- PARTIAL: Somewhat specific but could match too broadly
- MISSING: Generic, could describe dozens of different skills

### Content Quality (8-10)

#### 8. Avoids Stating the Obvious
> "Focus on information that pushes Claude out of its normal way of thinking."

**Why it matters**: Every line in a skill competes for attention. Lines that repeat what Claude already knows dilute the signal from lines that actually change behavior.

**What to look for**:
- Domain-specific knowledge Claude wouldn't have (internal conventions, team decisions)
- Counterintuitive instructions (things Claude would do differently by default)
- Absence of generic coding advice ("write clean code", "handle errors")

**Scoring**:
- PASS: Content is predominantly non-obvious, domain-specific
- PARTIAL: Mix of useful and obvious content
- MISSING: Mostly restates general coding practices

#### 9. Avoids Railroading
> "Give Claude the information it needs, but give it the flexibility to adapt."

**Why it matters**: Overly rigid step-by-step instructions break on edge cases. Skills are reused across many different prompts — they need to flex.

**What to look for**:
- Goal-oriented instructions ("ensure X happens") vs. rigid sequences ("Step 1, Step 2...")
- Escape hatches for edge cases ("if X doesn't apply, skip to...")
- Conditional branches rather than one-size-fits-all flows

**Scoring**:
- PASS: Goals with flexible paths, handles edge cases gracefully
- PARTIAL: Mostly sequential but has some flexibility / escape hatches
- MISSING: Rigid numbered steps with no adaptation points

#### 10. Has Examples
> "It's useful to include examples."

**Why it matters**: Examples ground abstract instructions in concrete behavior. They disambiguate intent better than paragraphs of explanation.

**What to look for**:
- Input → Output examples
- Before → After examples (for transformation skills)
- Edge case examples (not just happy path)

**Scoring**:
- PASS: Multiple concrete examples covering normal and edge cases
- PARTIAL: One or two examples, or only happy-path
- MISSING: No examples at all

### Advanced Patterns (11-14)

#### 11. Persistent Memory
> "Some skills can include a form of memory by storing data within them."

**Why it matters**: Memory lets the skill learn from past executions. It enables delta reporting, trend detection, and context continuity across sessions.

**What to look for**:
- Writes to `${CLAUDE_PLUGIN_DATA}` or a stable folder
- Log files, JSON stores, SQLite databases
- References to previous executions in the workflow

**Scoring**:
- PASS: Stores and reads execution history from stable storage
- PARTIAL: Mentions history but doesn't implement storage
- MISSING: No memory mechanism
- N/A: Skill is stateless by nature (e.g., one-shot code generation)

#### 12. On-Demand Hooks
> "Skills can include hooks that are only activated when the skill is called."

**Why it matters**: Hooks turn soft instructions ("don't edit X") into hard constraints (PreToolUse blocks Edit on X). They're the difference between "hoping Claude follows the rules" and "enforcing the rules."

**What to look for**:
- `hooks` in SKILL.md frontmatter
- PreToolUse matchers that block dangerous operations
- PostToolUse hooks for validation or logging

**Scoring**:
- PASS: Registers hooks that enforce critical constraints
- PARTIAL: Has hooks but they're cosmetic / non-critical
- MISSING: No hooks despite having safety-critical operations
- N/A: Skill has no safety-critical operations to guard

#### 13. Composes With Other Skills
> "You can just reference other skills by name, and the model will invoke them if they are installed."

**Why it matters**: Composition avoids duplication and leverages existing tested logic. A deploy skill that calls /ci-run is more maintainable than one that reimplements CI job triggering.

**What to look for**:
- References to other skills by name (`/skill-name`)
- Delegation of subtasks to specialized skills
- No reimplementation of logic available in sibling skills

**Scoring**:
- PASS: Composes with relevant sibling skills
- PARTIAL: References some skills but reimplements others
- MISSING: Reimplements logic that exists in sibling skills
- N/A: Skill is self-contained with no overlap

#### 14. Dual-Mode Support
> "Supporting both interactive and CI/headless modes."

**Why it matters**: Skills that work in CI can be automated (MR review bots, auto-deploy). Dual-mode multiplies the skill's reach.

**What to look for**:
- Detection of `$CI` environment variable
- Different output formats (terminal vs. structured markdown)
- No interactive prompts in CI mode (no AskUserQuestion)

**Scoring**:
- PASS: Explicit dual-mode with different behaviors per mode
- PARTIAL: Works in both modes but not explicitly designed for it
- MISSING: Only works interactively
- N/A: Skill is inherently interactive (e.g., user setup wizard)

### Classification (15)

#### 15. Clear Category
> "The best skills fit cleanly into one category; the more confusing ones straddle several."

**Why it matters**: Category clarity improves discoverability and maintainability. A skill that's half-review, half-deployment is harder to trigger correctly and harder to improve.

**What to look for**:
- Maps to exactly one Anthropic category
- Name and description align with the category
- Doesn't try to do too many things

**Scoring**:
- PASS: Fits cleanly into one category
- PARTIAL: Primary category clear but bleeds into another
- MISSING: Unclear category, tries to do too many things

---

## Maturity Levels

| Level | Score | Description |
|-------|-------|-------------|
| **Basic** | 0-5 | Functional but follows few best practices. Works for simple cases. |
| **Intermediate** | 6-10 | Solid foundation. Good structure and content, missing advanced patterns. |
| **Advanced** | 11-13 | Well-crafted. Uses progressive disclosure, scripts, composition. Room for polish. |
| **Expert** | 14-15 | Best-in-class. Deterministic where possible, flexible where needed, self-improving. |

---

## Scoring Calibration

These examples show how to score tricky edge cases consistently. When in doubt, reference these.

### N/A vs MISSING — common mistakes

| Skill type | Check | Correct | Wrong | Why |
|------------|-------|---------|-------|-----|
| `code-changelog` (one-shot file creation) | Memory (11) | N/A | MISSING | No useful history to track — each run is independent |
| `ci-deploy` (repeatable, env-specific) | Memory (11) | MISSING | N/A | A deploy log would be genuinely useful ("when did we last deploy?") |
| `product-discover` (read-only scan) | Hooks (12) | N/A | MISSING | Pure analysis, no mutations to guard |
| `code-changelog` (always interactive) | Dual-mode (14) | N/A | MISSING | No CI use case — changelogs are created during dev |
| `code-implement` (could run in CI) | Dual-mode (14) | MISSING | N/A | End-to-end automation is a natural CI use case |
| `glab-mr` (no env-specific values in SKILL.md) | Config (5) | N/A | MISSING | Templates loaded dynamically, no hardcoded IDs |
| `slack-ask-review` (hardcoded channel IDs) | Config (5) | MISSING | N/A | Channel IDs are environment-specific and should be in config |

### PARTIAL vs MISSING — calibration

| Situation | Score | Reasoning |
|-----------|-------|-----------|
| No `## Gotchas` section but real gotchas buried in `## Rules` | PARTIAL | The knowledge exists but lacks visibility — extracting it is a small effort |
| No gotchas anywhere in the skill | MISSING | No failure mode documentation at all |
| `references/` exists but is empty | MISSING | The Empty Shell anti-pattern — worse than absent because it's misleading |
| `references/` exists with files but SKILL.md doesn't say when to read them | PARTIAL | Files exist but discovery is accidental, not guided |
| Sequential steps (1-8) but with conditional branches per type | PARTIAL (railroading) | Has some flexibility but still locks Claude into a rigid sequence |
| Goal-oriented sections ("ensure X") with multiple valid paths | PASS (railroading) | Gives Claude room to adapt |

### Score thresholds — what scores mean in practice

- **6-7/15**: The skill works but relies heavily on Claude's general knowledge. Adding structure would make it notably more reliable.
- **8-9/15**: Solid skill with good descriptions and domain content. Missing advanced patterns (scripts, hooks, memory) that would make it professional-grade.
- **10-11/15**: Well-crafted. Usually has progressive disclosure and composition. One or two advanced patterns would push it to expert.
- **12-13/15**: Near-expert. Usually missing only scripts or hooks. A focused investment of 1-2 hours would close the gap.

---

## Anti-Patterns to Flag

1. **The Mega-Skill** — SKILL.md > 500 lines, no references, tries to do everything
2. **The Empty Shell** — Has structure (references/, scripts/) but files are stubs or unused
3. **The Copycat** — Reimplements logic from a sibling skill instead of composing
4. **The Dictator** — Rigid 15-step process with no escape hatches
5. **The Amnesiac** — Runs the same workflow every time with no memory of past runs
6. **The Leaky Abstraction** — Hardcodes environment-specific values that should be configurable
7. **The Undertriggerer** — Description is too generic or too narrow, causing missed activations
