7.6 KiB
7.6 KiB
Skill Best Practices
Comprehensive guidelines for creating effective Agent Skills.
Progressive Disclosure Architecture
Skills work in three layers:
Layer 1: Metadata (Always Loaded)
- What: YAML frontmatter with
nameanddescription - When: Pre-loaded at every session start
- Cost: ~100 tokens per skill
- Purpose: Trigger detection
Layer 2: Instructions (Triggered)
- What: Main SKILL.md content
- When: Loads when Claude determines skill applies
- Cost: Variable (keep under 1000 tokens)
- Purpose: Procedural guidance, workflows
Layer 3: Resources (On-Demand)
- What: Additional files, scripts, reference materials
- When: Only when explicitly needed
- Cost: Only when accessed
- Purpose: Deep reference, examples
Writing Effective Descriptions
The description field is your skill's trigger mechanism. Make it count.
Good Descriptions
✓ Specific use cases: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables" ✓ Clear triggers: "Use when building React components following atomic design principles" ✓ Domain clarity: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"
Poor Descriptions
✗ Too vague: "Helps with coding" ✗ No trigger context: "Python utilities" ✗ Feature list without purpose: "Has functions for A, B, and C"
Template
[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].
Example: "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."
Skill File Structure
Mandatory: SKILL.md
---
name: Your Skill Name # Max 64 chars
description: Clear description of usage # Max 1024 chars
---
Optional: Additional Resources
my-skill/
├── SKILL.md # Main entry (required)
├── reference.md # Deep reference
├── examples.md # Code samples
├── workflows/ # Step-by-step procedures
│ ├── advanced.md
│ └── beginner.md
└── scripts/ # Executable utilities
└── helper.sh
SKILL.md Content Structure
1. Start with "When to Use This Skill"
## When to Use This Skill
Use this skill when:
- [Primary scenario]
- [Secondary scenario]
- [Edge case to include]
Do NOT use this skill for:
- [Common confusion case]
- [Related but different scenario]
2. Structure for Scannability
## Quick Start
[Minimal example to get started]
## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two
## Advanced Techniques
[Less common but powerful approaches]
## Common Pitfalls
[Known issues and how to avoid them]
3. Include Concrete Examples
Always provide working examples, not abstract descriptions:
## Example: Creating a User Authentication Module
**Scenario**: Building JWT-based auth for a Flask API
**Steps**:
1. Install dependencies: `pip install pyjwt flask-login`
2. Create auth.py with [specific structure]
3. Configure middleware in app.py
4. Add protected routes with @login_required
**Result**: Users can register, login, and access protected endpoints
4. Reference Additional Files Explicitly
## Deep Dive: Advanced Patterns
For comprehensive examples, see [examples.md](examples.md).
For API reference, consult [reference.md](reference.md).
Optimizing for Token Efficiency
When to Split Files
Keep in SKILL.md if:
- Information needed for 80%+ of use cases
- Content is under ~2000 tokens
- Steps are sequential and interdependent
Split to separate file if:
- Content is mutually exclusive (e.g., Python vs JavaScript examples)
- Material is reference-heavy (API docs, configuration options)
- Information is advanced/edge-case focused
Code as Documentation
Executable scripts serve dual purposes:
- Tools Claude can run without loading code into context
- Documentation by example showing best practices
## Generating Boilerplate
Run the initialization script:
```bash
./scripts/init-project.sh my-app
This creates [description of what's created].
Claude can execute this without script code consuming context tokens.
## Development Workflow
### 1. Start with Evaluation
**Don't guess what skills you need.** Instead:
1. Run Claude on representative tasks
2. Identify where it struggles or asks repetitive questions
3. Capture successful patterns from those sessions
4. Codify into a skill
### 2. Iterate with Claude
Build skills collaboratively:
1. Work with Claude on a task
2. When you find a good solution, ask: "Should we capture this as a skill?"
3. Let Claude help structure the skill content
4. Test with new similar tasks
5. Refine based on actual usage
### 3. Monitor Trigger Accuracy
After creating a skill, test triggering:
**Test scenarios:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it
If triggering is unreliable, refine the `description` field.
### 4. Start Simple, Grow Organically
Begin with minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples
Add complexity only when needed:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when repeating same commands
- Create reference files for API documentation
## Common Anti-Patterns
### ❌ Generic Description
```yaml
description: Helps with coding
Fix: Be specific about domain and triggers
❌ No Process Defined
You are a code reviewer. Review code.
Fix: Define step-by-step process
❌ All Tools Granted
# Omitting tools when only reads needed
Fix: Whitelist minimum required tools
❌ Verbose Prompt
You are an expert developer with 20 years of experience... [3000 words]
Fix: Be concise, focus on process and format
Testing Skills
Test Plan Template
# Positive Tests (Should Activate)
1. "Create REST endpoint for user auth"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate)
1. "Write unit tests for API"
Expected: Does not activate
Actual: ___
## Results
- Precision: X%
- Recall: Y%
Security Considerations
Never Include
- Hardcoded credentials or API keys
- Personal identifying information
- Proprietary code without permission
- Instructions to make unsafe system changes
Always Consider
- Can this skill be misused if shared?
- Does it access sensitive file locations?
- Are external dependencies from trusted sources?
Skill Metadata Checklist
Before finalizing:
- Name is under 64 characters
- Description is under 1024 characters
- Description includes specific use cases
- Description mentions when to trigger
- SKILL.md has YAML frontmatter
- "When to Use This Skill" section present
- At least one concrete example
- No sensitive information
- File references are accurate
- Tested triggering scenarios
- Tested NOT triggering scenarios
Summary
Best practices in order of importance:
- Write specific descriptions with clear triggers
- Structure progressively (metadata → core → details)
- Start simple and grow based on actual needs
- Test thoroughly with positive and negative scenarios
- Optimize tokens by splitting appropriately
- Provide examples not just theory
- Monitor usage and refine based on feedback