14 Reusable Agent Skill Design Patterns from Anthropic’s Official Best Practices

Discovery and Selection

When a skill library contains dozens of skills, Claude must know which one to invoke. The Activation Metadata pattern recommends using a precise description field (not a vague summary) that includes what the skill does, when to trigger it, and key trigger keywords. This description is the primary signal for Claude’s selection. The pattern applies to all skills; a good description must stay within the 1024‑character limit (or 1536 characters when combined with when_to_use in Claude Code).

The Exclusion Clause pattern complements activation metadata by explicitly stating when the skill should not be used. For overlapping skills (e.g., document processing vs. code generation), an exclusion clause prevents ambiguous selection. It should list unsuitable scenarios, hand‑off cases, and situations where Claude can act alone. This pattern is useful for any skill, especially those with overlapping functionality, but adds maintenance overhead as the skill set grows.

Context Economy

Tokens are a shared resource across skills, conversation history, and the current request. The Context Budget pattern advises keeping each description concise—only include information that a "smart enough" Claude cannot infer. Redundant explanations waste context space.

The Progressive Disclosure pattern treats SKILL.md as a directory rather than a monolithic file. Keep the main file under 500 lines, split detailed sections (e.g., FORMS.md, REFERENCE.md) into separate files, and load them only when needed. This reduces token consumption and improves clarity.

Instruction Calibration

Balancing strictness and flexibility is key. The Control Tuning pattern selects instruction rigidity based on the task’s fragility: high freedom for open‑ended tasks, medium for semi‑structured workflows, and low for high‑risk operations (e.g., database migrations).

The Explain‑the‑Why pattern pairs rules with their rationale, allowing Claude to reason beyond literal commands. For example, preferring "use constructor injection because field injection harms testability" over a blunt "must use constructor injection".

The Template Scaffold pattern provides a placeholder‑filled template that defines output structure (strict or flexible). Combined with examples, it ensures consistent formatting while allowing stylistic variation.

The In‑Skill Examples pattern embeds a few input/output examples directly in the skill, guiding Claude’s style and format without exhaustive prose.

The Known Gotchas pattern lists common failure modes (e.g., empty PDF results, platform‑specific command issues) so Claude can anticipate and avoid pitfalls.

Workflow Control

Complex multi‑step processes benefit from explicit control structures.

The Execution Checklist pattern turns a workflow into a tickable list, keeping unfinished items visible and preventing premature completion.

The Self‑Correcting Loop pattern introduces an explicit generate‑validate‑repair cycle, ensuring each step is verified before proceeding.

The Plan‑Validate‑Execute pattern inserts a verifiable intermediate artifact (e.g., a JSON plan) between understanding and execution, guaranteeing that high‑risk actions are only performed after successful validation.

Executable Code

Deterministic operations should be offloaded to scripts.

The Utility Bundle pattern collects reusable scripts in a scripts/ directory and invokes them via Bash, feeding only script output into Claude’s context.

The Autonomy Calibration pattern restricts a skill’s capabilities by explicitly listing allowed-tools in the YAML, granting only the minimal required permissions (e.g., Read/Grep for audits, Write for documentation, Bash for deployments). This is not a sandbox but a pre‑approval list that must be combined with proper permission policies.

These fourteen patterns address the most common failure points in skill design: discoverability, context usage, instruction clarity, workflow robustness, and safe execution. By applying them, developers can build Claude Agent Skills that remain effective as models and tooling evolve.