Top Agent Skills

Agent Skills

Modular capability packages that extend Claude's functionality. Learn how to develop, deploy, and optimize Agent Skills to achieve advanced features like code execution, document processing, and data analysis.

Best Practices

Development Best Practices

Following best practices ensures reliable activation, high performance, efficiency, and security

1. Start with the Right Foundation

Use the built-in skill-creator Skill

The easiest and recommended entry point. It interactively guides you: Describe your workflow, and Claude generates the folder structure, SKILL.md, and resources automatically.

Tip: Start here for any new skill development
Identify gaps first

Evaluate Claude's baseline performance on real tasks without the Skill. Build incrementally to address specific weaknesses.

Tip: Test without the skill to understand what's missing
Narrow scope for modularity

Design Skills for focused tasks (e.g., "pandas data cleaning" instead of "all data analysis"). This enables composability—Claude can chain multiple narrow Skills naturally.

Tip: Smaller, focused skills are more reusable

2. Iterative Development Workflow

Dual-Claude testing

Use one Claude instance ("Claude A") to design/refine the Skill, and another ("Claude B") to test it in real workflows.

  • Observe activation
  • Monitor behavior
  • Note failures
  • Iterate improvements
Test on actual tasks

Run end-to-end workflows repeatedly. Pay attention to how Claude reads files, invokes scripts, or handles edge cases.

Focus on:
File reading patterns
Script invocation
Edge case handling
Version iteratively

Use the API /v1/skills endpoint for versioning and management. Track changes in SKILL.md.

Example: Add a version history section to SKILL.md

3. YAML Frontmatter Optimization

Critical for Activation
name

Unique, descriptive, kebab-case

Example:
code-reviewer
description
Critical

Third-person/imperative, include what + when + keywords

Example:
Reviews code for best practices, security issues, and performance. Use when analyzing pull requests, debugging code, or improving code quality.
allowed-tools

Optional but recommended for least-privilege

Example:
Read, Execute only

4. Structure and Progressive Disclosure

Guidelines
  • Keep SKILL.md concise (<10k tokens): High-level overview, quick workflows, navigation links
  • Offload details to reference files (loaded on-demand)
  • Use markdown links for progressive loading
Folder Structure
skill-folder/
├── SKILL.md              # Main instructions
├── REFERENCE.md          # In-depth guidelines
├── EXAMPLES.md           # Full input/output pairs
├── TROUBLESHOOTING.md    # Errors and fixes
├── scripts/              # Executables
└── templates/            # File templates
Progressive Loading
[Detailed workflow](./REFERENCE.md)—Claude loads only when needed, saving tokens.

5. Reliability Techniques

Concrete examples

Include 3–5 varied, full examples in SKILL.md or EXAMPLES.md

Essential for consistent behavior
Phased workflows

Explicit steps: Plan → Execute → Validate → Cleanup

PlanExecuteValidateCleanup
Error handling

Anticipate failures; instruct retries, validation loops

Prefer scripts for determinism

Offload repetitive/computational tasks to scripts/ (Python/Bash)

Benefit: More reliable than LLM generation
Output standards

Define checklists, templates, or validation scripts for consistency

6. Security and Trust

Trusted sources only

Create your own or use Anthropic's. Audit third-party Skills thoroughly.

  • Review SKILL.md
  • Examine all scripts
  • Check permissions
Least-privilege

Use allowed-tools to limit access to only what's necessary.

Enterprise governance

Provision centrally; monitor usage for anomalies.

7. Advanced Tips

Composability

Combine with other Skills, MCP tools, or subagents for complex workflows.

When to Use Skills vs. Alternatives
SkillsReusable procedural expertise across sessions
Prompts/ProjectsOne-off or chat-specific tasks
SubagentsIndependent specialized agents
Resources
Anthropic Engineering Blog

Equipping agents for the real world with Agent Skills

anthropic.com/blog
GitHub Repository

Study pre-built document Skills

github.com/anthropics/skills
Documentation

Best practices guide in Claude platform docs

docs.claude.com

Start Building Robust Skills

Apply these practices to create robust, scalable Skills that turn Claude into a true specialist. Start with skill-creator, test rigorously, and refine based on real usage—your Skills will improve dramatically over iterations!