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

Based on Anthropic’s official skill‑authoring best‑practice documentation, this article distills fourteen reusable design patterns for building Claude Agent Skills. The patterns are organized into five categories—Discovery & Selection, Context Economy, Instruction Calibration, Workflow Control, and Executable Code—each illustrated with concrete examples, trade‑offs, and actionable recommendations.

Discovery & Selection

1. Activation Metadata pattern – When a skill library contains dozens of skills, Claude must decide which one to invoke. The description field, not a vague summary like “process documents”, is the decisive signal. A good description should contain three elements:

What the skill does (function)

When it should be triggered (scenario)

Which keywords activate it

Anthropic’s skill-creator even recommends making the description more proactive, e.g., “Even if the user does not mention a dashboard, trigger this skill when data‑visualisation or internal metrics are referenced.”

Applicable scenario: All skills should use this pattern; a poor entry point makes the rest of the skill irrelevant.

Trade‑off: The description length is limited to 1024 characters in the open Agent Skills spec and 1536 characters (including optional when_to_use) in Claude Code, so every word must balance trigger terms, exclusions, and domain keywords.

2. Exclusion Clause pattern – Complement the positive trigger with explicit “when NOT to use” clauses. For overlapping skills (e.g., a “document processing” skill and a “code generation” skill both saying “handle all text”), a clear exclusion prevents ambiguous selection. Ruben Hassid calls this the most critical line in the description. A good exclusion clause states:

Scenarios where the skill does not apply

Content that should be delegated to another skill

Cases where Claude alone suffices

Example:

"Do not use for blog posts, newsletters, tweets, or long‑form content."

Applicable scenario: Almost every skill, especially those with overlapping responsibilities.

Trade‑off: Maintaining exclusions grows with the number of skills; neglect leads to conflicts or gaps.

Context Economy

3. Context Budget pattern – Repeating generic explanations (e.g., “what a PDF is”) wastes token budget across many skills. Since Claude already knows such fundamentals, each paragraph should earn its token cost. The rule of thumb: if removing a sentence does not confuse a “smart enough” reader, it is likely redundant.

Trade‑offs: Keep terminology consistent (e.g., always use field instead of alternating field / box / element) and avoid time‑sensitive phrasing like “before August 2025”.

4. Progressive Disclosure pattern – Treat the main SKILL.md as a table of contents, not a monolithic repository. Keep the primary file under ~500 lines and split detailed sections (e.g., FORMS.md, REFERENCE.md, reference/finance.md) into separate files that are loaded only when needed.

Practical tips:

Place long reference files behind a TOC so Claude knows the overall structure even if truncated.

Store reusable scripts in a scripts/ directory; they run in the background and do not consume token space.

Applicable scenario: When SKILL.md exceeds ~300 lines, consider splitting.

Trade‑off: More files increase authoring complexity and require the model to decide which file to load next.

Instruction Calibration

5. Control Tuning pattern – Adjust instruction strictness based on the task’s fragility. Ask “How much deviation is acceptable?” and choose one of three freedom levels:

High freedom – free‑form text (e.g., "Use your judgment") for open‑ended tasks like code review.

Medium freedom – pseudo‑code or parameterised steps for tasks that need flexibility, such as deployments.

Low freedom – precise scripts or hard constraints (e.g., "Do not modify") for high‑risk operations like database migrations.

The tone also acts as a lever; setting a role at the start (e.g., “You are a senior code reviewer who cares more about correctness than style”) influences downstream judgments, especially in reference‑type skills.

6. Explain‑the‑Why pattern – Instead of a bare ALWAYS / NEVER / MUST rule, first state the rule, then provide the rationale. Example:

"Use constructor injection. Field injection harms testability because it requires mocking the Spring context."

Compared with "Must use constructor injection, never use field injection.", the former gives Claude a reasoning path, making it more robust when the rule does not cover edge cases.

7. Template Scaffold pattern – Provide a skeleton with placeholders so Claude fills in the structure. Two variants exist:

Strict template – Enforced structure (e.g., JSON contracts) for machine‑parseable output.

Flexible template – Recommended structure that can be adjusted, suitable for human‑readable documents.

8. In‑Skill Examples pattern – Supply a few input/output pairs inside the skill (few‑shot style). Example code block:

Input: [user example]
Output: [expected output]

Templates define shape; examples define style. Combining both yields consistent, well‑formatted results.

9. Known Gotchas pattern – List failure modes that the skill does not handle (e.g., “PDF scan may return an empty array; check page type first”). Adding a dedicated “Gotchas” section in SKILL.md helps Claude avoid silent mis‑behaviour.

Workflow Control

10. Execution Checklist pattern – Render multi‑step processes as a visible checklist:

- [ ] Step 1: ...
- [ ] Step 2: ...
- [ ] Step 3: ...

Unfinished items remain visible each turn, preventing premature completion.

11. Self‑Correcting Loop pattern – Introduce an explicit loop: generate → validate → if failure, fix → re‑validate. Validation can be a script (e.g., python validate.py fields.json) or a rule check against a style guide.

12. Plan‑Validate‑Execute pattern – Insert a verifiable intermediate artifact (often JSON) between “understand task” and “perform action”. Only after the plan passes validation does Claude proceed, reducing the risk of irreversible errors.

Executable Code

13. Utility Bundle pattern – Move deterministic logic into reusable scripts stored under scripts/. Claude calls them via Bash, feeding only the script’s output into the context. Scripts should handle their own errors, provide sensible defaults, and avoid magic numbers.

14. Autonomy Calibration pattern – Restrict a skill’s capabilities by explicitly listing allowed tools in the YAML allowed-tools field. Examples:

Security audit: Read, Grep, Glob Document generation: Read, Write Deployment task: Bash Note that allowed-tools is a pre‑approval, not a hard sandbox; proper permission policies are still required.

These fourteen patterns address the most common failure points in skill design. By applying them, developers can build Claude extensions that are discoverable, token‑efficient, robust to edge cases, and safe to execute.