Anthropic Best Practices

For conceptual background on how Skills work, see the Skills overview (opens in a new tab).

Core principles

Concise is key

The context window (opens in a new tab) is a public good. Your Skill shares the context window with everything else your agent needs to know, including:

• The system prompt
• Conversation history
• Other Skills’ metadata
• Your actual request

Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Agents read SKILL.md only when the Skill becomes relevant, and read additional files only as needed. However, being concise in SKILL.md still matters: once an agent loads it, every token competes with conversation history and other context.

Default assumption: Agents are already very smart

Only add context agents don’t already have. Challenge each piece of information:

• “Does the agent really need this explanation?”
• “Can I assume the agent knows this?”
• “Does this paragraph justify its token cost?”

Good example: Concise (approximately 50 tokens):

Bad example: Too verbose (approximately 150 tokens):

The concise version assumes the agent knows what PDFs are and how libraries work.

Set appropriate degrees of freedom

Match the level of specificity to the task’s fragility and variability.

High freedom (text-based instructions):

Use when:

• Multiple approaches are valid
• Decisions depend on context
• Heuristics guide the approach

Example:

Medium freedom (pseudocode or scripts with parameters):

Use when:

• A preferred pattern exists
• Some variation is acceptable
• Configuration affects behavior

Example:

Low freedom (specific scripts, few or no parameters):

Use when:

• Operations are fragile and error-prone
• Consistency is critical
• A specific sequence must be followed

Example:

Analogy: Think of the agent as a robot exploring a path:

• Narrow bridge with cliffs on both sides: There’s only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
• Open field with no hazards: Many paths lead to success. Give general direction and trust the agent to find the best route (high freedom). Example: code reviews where context determines the best approach.

Test with all models you plan to use

Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.

Testing considerations by model:

• Claude Haiku (fast, economical): Does the Skill provide enough guidance?
• Claude Sonnet (balanced): Is the Skill clear and efficient?
• Claude Opus (powerful reasoning): Does the Skill avoid over-explaining?

What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.

Skill structure

• name - Human-readable name of the Skill (64 characters maximum)
• description - One-line description of what the Skill does and when to use it (1024 characters maximum)

For complete Skill structure details, see the Skills overview (opens in a new tab).

Naming conventions

Use consistent naming patterns to make Skills easier to reference and discuss. We recommend using gerund form (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.

Good naming examples (gerund form):

• “Processing PDFs”
• “Analyzing spreadsheets”
• “Managing databases”
• “Testing code”
• “Writing documentation”

Acceptable alternatives:

• Noun phrases: “PDF Processing”, “Spreadsheet Analysis”
• Action-oriented: “Process PDFs”, “Analyze Spreadsheets”

Avoid:

• Vague names: “Helper”, “Utils”, “Tools”
• Overly generic: “Documents”, “Data”, “Files”
• Inconsistent patterns within your skill collection

Consistent naming makes it easier to:

• Reference Skills in documentation and conversations
• Understand what a Skill does at a glance
• Organize and search through multiple Skills
• Maintain a professional, cohesive skill library

Writing effective descriptions

The description field enables Skill discovery and should include both what the Skill does and when to use it.

• Good: “Processes Excel files and generates reports”
• Avoid: “I can help you process Excel files”
• Avoid: “You can use this to process Excel files”

Be specific and include key terms. Include both what the Skill does and specific triggers/contexts for when to use it.

Each Skill has exactly one description field. The description is critical for skill selection: agents use it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for an agent to know when to select this Skill, while the rest of SKILL.md provides the implementation details.

Effective examples:

PDF Processing skill:

Excel Analysis skill:

Git Commit Helper skill:

Avoid vague descriptions like these:

Progressive disclosure patterns

SKILL.md serves as an overview that points agents to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see How Skills work (opens in a new tab) in the overview.

Practical guidance:

• Keep SKILL.md body under 500 lines for optimal performance
• Split content into separate files when approaching this limit
• Use the patterns below to organize instructions, code, and resources effectively

Visual overview: From simple to complex

A basic Skill starts with just a SKILL.md file containing metadata and instructions:

As your Skill grows, you can bundle additional content that agents load only when needed:

The complete Skill directory structure might look like this:

Pattern 1: High-level guide with references

Agents load FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.

Pattern 2: Domain-specific organization

For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, the agent only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.

Pattern 3: Conditional details

Show basic content, link to advanced content:

Agents read REDLINING.md or OOXML.md only when the user needs those features.

Avoid deeply nested references

Agents may partially read files when they’re referenced from other referenced files. When encountering nested references, an agent might use commands like head -100 to preview content rather than reading entire files, resulting in incomplete information.

Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md to ensure agents read complete files when needed.

Bad example: Too deep:

Good example: One level deep:

Structure longer reference files with table of contents

For reference files longer than 100 lines, include a table of contents at the top. This ensures agents can see the full scope of available information even when previewing with partial reads.

Example:

Agents can then read the complete file or jump to specific sections as needed.

For details on how this filesystem-based architecture enables progressive disclosure, see the Runtime environment section in the Advanced section below.

Workflows and feedback loops

Use workflows for complex tasks

Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that the agent can copy into its response and check off as it progresses.

Example 1: Research synthesis workflow (for Skills without code):

This example shows how workflows apply to analysis tasks that don’t require code. The checklist pattern works for any complex, multi-step process.

Example 2: PDF form filling workflow (for Skills with code):

Clear steps prevent agents from skipping critical validation. The checklist helps both you and the agent track progress through multi-step workflows.

Implement feedback loops

Common pattern: Run validator → fix errors → repeat

This pattern greatly improves output quality.

Example 1: Style guide compliance (for Skills without code):

This shows the validation loop pattern using reference documents instead of scripts. The “validator” is STYLE_GUIDE.md, and the agent performs the check by reading and comparing.

Example 2: Document editing process (for Skills with code):

The validation loop catches errors early.

Content guidelines

Avoid time-sensitive information

Don’t include information that will become outdated:

Bad example: Time-sensitive (will become wrong):

Good example (use “old patterns” section):

The old patterns section provides historical context without cluttering the main content.

Use consistent terminology

Choose one term and use it throughout the Skill:

Good - Consistent:

• Always “API endpoint”
• Always “field”
• Always “extract”

Bad - Inconsistent:

• Mix “API endpoint”, “URL”, “API route”, “path”
• Mix “field”, “box”, “element”, “control”
• Mix “extract”, “pull”, “get”, “retrieve”

Consistency helps agents understand and follow instructions.

Common patterns

Template pattern

Provide templates for output format. Match the level of strictness to your needs.

For strict requirements (like API responses or data formats):

For flexible guidance (when adaptation is useful):

Examples pattern

For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:

Examples help agents understand the desired style and level of detail more clearly than descriptions alone.

Conditional workflow pattern

Guide agents through decision points:

Evaluation and iteration

Build evaluations first

Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems rather than documenting imagined ones.

Evaluation-driven development:

1. Identify gaps: Run your agent on representative tasks without a Skill. Document specific failures or missing context
2. Create evaluations: Build three scenarios that test these gaps
3. Establish baseline: Measure the agent’s performance without the Skill
4. Write minimal instructions: Create just enough content to address the gaps and pass evaluations
5. Iterate: Execute evaluations, compare against baseline, and refine

This approach ensures you’re solving actual problems rather than anticipating requirements that may never materialize.

Evaluation structure:

Develop Skills iteratively with the agent

The most effective Skill development process involves the agent itself. Work with one instance (“Agent A”) to create a Skill that will be used by other instances (“Agent B”). Agent A helps you design and refine instructions, while Agent B tests them in real tasks. This works because the underlying models understand both how to write effective agent instructions and what information agents need.

Creating a new Skill:

1. Complete a task without a Skill: Work through a problem with Agent A using normal prompting. As you work, you’ll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.

2. Identify the reusable pattern: After completing the task, identify what context you provided that would be useful for similar future tasks.

   Example: If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like “always exclude test accounts”), and common query patterns.

3. Ask Agent A to create a Skill: “Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts.”

4. Review for conciseness: Check that Agent A hasn’t added unnecessary explanations. Ask: “Remove the explanation about what win rate means - the agent already knows that.”

5. Improve information architecture: Ask Agent A to organize the content more effectively. For example: “Organize this so the table schema is in a separate reference file. We might add more tables later.”

6. Test on similar tasks: Use the Skill with Agent B (a fresh instance with the Skill loaded) on related use cases. Observe whether Agent B finds the right information, applies rules correctly, and handles the task successfully.

7. Iterate based on observation: If Agent B struggles or misses something, return to Agent A with specifics: “When the agent used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?”

Iterating on existing Skills:

The same hierarchical pattern continues when improving Skills. You alternate between:

• Working with Agent A (the expert who helps refine the Skill)
• Testing with Agent B (the agent using the Skill to perform real work)
• Observing Agent B’s behavior and bringing insights back to Agent A

1. Use the Skill in real workflows: Give Agent B (with the Skill loaded) actual tasks, not test scenarios

2. Observe Agent B’s behavior: Note where it struggles, succeeds, or makes unexpected choices

   Example observation: “When I asked Agent B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule.”

3. Return to Agent A for improvements: Share the current SKILL.md and describe what you observed. Ask: “I noticed Agent B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it’s not prominent enough?”

4. Review Agent A’s suggestions: Agent A might suggest reorganizing to make rules more prominent, using stronger language like “MUST filter” instead of “always filter”, or restructuring the workflow section.

5. Apply and test changes: Update the Skill with Agent A’s refinements, then test again with Agent B on similar requests

6. Repeat based on usage: Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.

Gathering team feedback:

1. Share Skills with teammates and observe their usage
2. Ask: Does the Skill activate when expected? Are instructions clear? What’s missing?
3. Incorporate feedback to address blind spots in your own usage patterns

Why this approach works: Agent A understands agent needs, you provide domain expertise, Agent B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.

Observe how agents navigate Skills

As you iterate on Skills, pay attention to how agents actually use them in practice. Watch for:

• Unexpected exploration paths: Does the agent read files in an order you didn’t anticipate? This might indicate your structure isn’t as intuitive as you thought
• Missed connections: Does the agent fail to follow references to important files? Your links might need to be more explicit or prominent
• Overreliance on certain sections: If the agent repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
• Ignored content: If the agent never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions

Iterate based on these observations rather than assumptions. The ‘name’ and ‘description’ in your Skill’s metadata are particularly critical. Agents use these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.

Anti-patterns to avoid

Avoid Windows-style paths

Always use forward slashes in file paths, even on Windows:

• ✓ Good: scripts/helper.py, reference/guide.md
• ✗ Avoid: scripts\helper.py, reference\guide.md

Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.

Avoid offering too many options

Don’t present multiple approaches unless necessary:

Advanced: Skills with executable code

The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to Checklist for effective Skills.

Solve, don’t punt

When writing scripts for Skills, handle error conditions rather than punting to the agent.

Good example: Handle errors explicitly:

Bad example: Punt to the agent:

Configuration parameters should also be justified and documented to avoid “voodoo constants” (Ousterhout’s law). If you don’t know the right value, how will the agent determine it?

Good example: Self-documenting:

Bad example: Magic numbers:

Provide utility scripts

Even if your agent could write a script, pre-made scripts offer advantages:

Benefits of utility scripts:

• More reliable than generated code
• Save tokens (no need to include code in context)
• Save time (no code generation required)
• Ensure consistency across uses

The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and the agent can execute it without loading its contents into context.

Important distinction: Make clear in your instructions whether the agent should:

• Execute the script (most common): “Run analyze_form.py to extract fields”
• Read it as reference (for complex logic): “See analyze_form.py for the field extraction algorithm”

For most utility scripts, execution is preferred because it’s more reliable and efficient. See the Runtime environment section below for details on how script execution works.

Example:

Use visual analysis

When inputs can be rendered as images, have the agent analyze them:

Agent vision capabilities help understand layouts and structures.

Create verifiable intermediate outputs

When agents perform complex, open-ended tasks, they can make mistakes. The “plan-validate-execute” pattern catches errors early by having the agent first create a plan in a structured format, then validate that plan with a script before executing it.

Example: Imagine asking the agent to update 50 form fields in a PDF based on a spreadsheet. Without validation, it might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.

Solution: Use the workflow pattern shown above (PDF form filling), but add an intermediate changes.json file that gets validated before applying changes. The workflow becomes: analyze → create plan file → validate plan → execute → verify.

Why this pattern works:

• Catches errors early: Validation finds problems before changes are applied
• Machine-verifiable: Scripts provide objective verification
• Reversible planning: The agent can iterate on the plan without touching originals
• Clear debugging: Error messages point to specific problems

When to use: Batch operations, destructive changes, complex validation rules, high-stakes operations.

Implementation tip: Make validation scripts verbose with specific error messages like “Field ‘signature_date’ not found. Available fields: customer_name, order_total, signature_date_signed” to help the agent fix issues.

Package dependencies

Skills run in the code execution environment with platform-specific limitations:

• claude.ai: Can install packages from npm and PyPI and pull from GitHub repositories
• Anthropic API: Has no network access and no runtime package installation

List required packages in your SKILL.md and verify they’re available in the code execution tool documentation (opens in a new tab).

Runtime environment

Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see The Skills architecture (opens in a new tab) in the overview.

How this affects your authoring:

How agents access Skills:

1. Metadata pre-loaded: At startup, the name and description from all Skills’ YAML frontmatter are loaded into the system prompt
2. Files read on-demand: Agents use their file-reading tools to access SKILL.md and other files from the filesystem when needed
3. Scripts executed efficiently: Utility scripts can be executed via bash without loading their full contents into context. Only the script’s output consumes tokens
4. No context penalty for large files: Reference files, data, or documentation don’t consume context tokens until actually read

• File paths matter: Agents navigate your skill directory like a filesystem. Use forward slashes (reference/guide.md), not backslashes
• Name files descriptively: Use names that indicate content: form_validation_rules.md, not doc2.md
• Organize for discovery: Structure directories by domain or feature
  • Good: reference/finance.md, reference/sales.md
  • Bad: docs/file1.md, docs/file2.md
• Bundle comprehensive resources: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
• Prefer scripts for deterministic operations: Write validate_form.py rather than asking the agent to generate validation code
• Make execution intent clear:
  • “Run analyze_form.py to extract fields” (execute)
  • “See analyze_form.py for the extraction algorithm” (read as reference)
• Test file access patterns: Verify the agent can navigate your directory structure by testing with real requests

Example:

When the user asks about revenue, the agent reads SKILL.md, sees the reference to reference/finance.md, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Agents can navigate and selectively load exactly what each task requires.

For complete details on the technical architecture, see How Skills work (opens in a new tab) in the Skills overview.

MCP tool references

If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid “tool not found” errors.

Format: ServerName:tool_name

Example:

Where:

• BigQuery and GitHub are MCP server names
• bigquery_schema and create_issue are the tool names within those servers

Without the server prefix, agents may fail to locate the tool, especially when multiple MCP servers are available.

Avoid assuming tools are installed

Don’t assume packages are available:

Technical notes

YAML frontmatter requirements

The SKILL.md frontmatter requires name (64 characters max) and description (1024 characters max) fields. See the Skills overview (opens in a new tab) for complete structure details.

Token budgets

Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the Skills overview (opens in a new tab).

Checklist for effective Skills

Before sharing a Skill, verify:

Core quality

• Not done: Description is specific and includes key terms
• Not done: Description includes both what the Skill does and when to use it
• Not done: SKILL.md body is under 500 lines
• Not done: Additional details are in separate files (if needed)
• Not done: No time-sensitive information (or in “old patterns” section)
• Not done: Consistent terminology throughout
• Not done: Examples are concrete, not abstract
• Not done: File references are one level deep
• Not done: Progressive disclosure used appropriately
• Not done: Workflows have clear steps

Code and scripts

• Not done: Scripts solve problems rather than punt to the agent
• Not done: Error handling is explicit and helpful
• Not done: No “voodoo constants” (all values justified)
• Not done: Required packages listed in instructions and verified as available
• Not done: Scripts have clear documentation
• Not done: No Windows-style paths (all forward slashes)
• Not done: Validation/verification steps for critical operations
• Not done: Feedback loops included for quality-critical tasks

Testing

• Not done: At least three evaluations created
• Not done: Tested with Haiku, Sonnet, and Opus
• Not done: Tested with real usage scenarios
• Not done: Team feedback incorporated (if applicable)

Next steps