claude-skills
Claude Code Skills — on-demand knowledge / workflow packages. The descriptor stays resident in claude-code‘s context; the full body loads only when invoked. anthropic internally calls this progressive disclosure (2026-04-27-claude-code-architecture-governance-engineering).
A good Skill
- Description tells the model when to use me, not what I am — these are very different (tw93).
- Has explicit steps, inputs, outputs, and a stop condition.
- Body holds navigation and core constraints; bulk reference goes in supporting files, not
SKILL.md. - Side-effecting Skills set
disable-model-invocation: trueso the model can’t decide on its own to run them. - Routing condition, not feature description. “Use when / Don’t use when” + a few counter-examples. Most routing failures aren’t capability problems — they’re boundary problems in the description (agent-computer-interface).
- Counter-examples matter more than people expect. A measurement cited in 2026-04-27-agent-principles-architecture-engineering: descriptors with no counter-examples landed at 53% accuracy versus a 73% baseline; descriptors with counter-examples reached 85% accuracy and response time fell 18.1%.
Standard layout
.claude/skills/
└── incident-triage/
├── SKILL.md
├── runbook.md
├── examples.md
└── scripts/
└── collect-context.shSKILL.md defines task semantics, boundaries, the execution skeleton; supporting files supply domain detail; scripts handle deterministic context-gathering.
Three Skill archetypes (with kaku examples)
| Type | Purpose | Example |
|---|---|---|
| Checklist (quality gate) | Run before a release; ensure nothing is missed | release-check: build passes, clippy clean, version bumped, CHANGELOG updated, kaku doctor clean |
| Workflow (standardized op) | Risky multi-step procedure with explicit rollback | config-migration: backup → dry-run → apply → verify; rollback path included; disable-model-invocation: true because side-effecting |
| Domain expert (decision framework) | Force evidence collection along a fixed path | runtime-diagnosis: capture kaku doctor + last 50 log lines + plugin state, then route via a decision matrix to root cause |
A fourth archetype from anthropic‘s own loop post (2026-07-12-loop-engineering-getting-started): the verification skill — encode your manual acceptance checks so the agent verifies its own work end-to-end (the post’s verify-frontend-change example: browser interaction, before/after screenshots, clean console, DevTools performance trace). Functionally a Checklist skill, but aimed at closing the verifier-loop inside a single turn — the first rung of loop-engineering‘s hand-off ladder. Skills can also ship scripts for deterministic work (a form-filling script the agent runs each time) because running a script is cheaper than re-deriving the steps by reasoning.
Descriptors are stealing your context
Every enabled Skill’s descriptor is resident — token-budget pressure compounds across many Skills (context-engineering).
# Wasteful — ~45 tokens
description: |
This skill helps you review code changes in Rust projects.
It checks for common issues like unsafe code, error handling...
Use this when you want to ensure code quality before merging.
# Tight — ~9 tokens
description: Use for PR reviews with focus on correctness.When to enable auto-invoke
| Use frequency | Setting |
|---|---|
| > 1× per session | Auto-invoke; tighten descriptor |
| < 1× per session | disable-auto-invoke; trigger manually; descriptor leaves the resident set |
| < 1× per month | Delete the Skill; convert to plain doc in AGENTS.md |
Anti-patterns
- Description too short (
description: help with backend) — fires for anything backend-shaped. - Body too long — hundreds of lines of operating manual stuffed into
SKILL.md. - One Skill covers five jobs (review + deploy + debug + docs + incident).
- Side-effecting Skill with auto-invoke enabled — model decides on its own to run a destructive operation.
- No rate-limit guidance in the description. When a Skill triggers external API writes, write the rate-limit expectations in the description itself: batch where possible, avoid one-by-one loops, back off on 429. The Skill body alone isn’t enough — the model has to see the constraint at routing time (2026-04-27-agent-principles-architecture-engineering).
Skills vs. MCP — different context cost shapes
2026-04-27-agent-principles-architecture-engineering sharpens the difference: many MCP servers return full results directly to the model and chew context fast. CLI + a one-line description Skill is closer to the model’s natural tool-call shape and stays small for read-and-filter jobs. MCP earns its place where state matters (e.g. Playwright maintaining a browser session) — but for “fetch and pass through,” Skills are usually the lighter primitive.