457 lines
12 KiB
Markdown
457 lines
12 KiB
Markdown
---
|
|
name: Skill Creator
|
|
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use when building new skills or improving existing ones.
|
|
---
|
|
|
|
# Skill Creation Best Practices
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- Creating a new Agent Skill from scratch
|
|
- Improving or refactoring an existing skill
|
|
- Debugging why a skill isn't triggering correctly
|
|
- Understanding skill architecture and design patterns
|
|
- Optimizing skill structure for token efficiency
|
|
|
|
## Core Principle: Progressive Disclosure
|
|
|
|
**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works in three layers:
|
|
|
|
### Layer 1: Metadata (Always Loaded)
|
|
- **What**: YAML frontmatter with `name` and `description`
|
|
- **When**: Pre-loaded at every session start
|
|
- **Cost**: ~100 tokens per skill
|
|
- **Purpose**: Trigger detection - helps Claude decide if skill is relevant
|
|
|
|
### Layer 2: Instructions (Triggered)
|
|
- **What**: Main SKILL.md content
|
|
- **When**: Loads when Claude determines skill applies
|
|
- **Cost**: Variable (keep focused and concise)
|
|
- **Purpose**: Procedural guidance, workflows, best practices
|
|
|
|
### Layer 3: Resources (On-Demand)
|
|
- **What**: Additional files, scripts, reference materials
|
|
- **When**: Only when explicitly needed
|
|
- **Cost**: Only when accessed
|
|
- **Purpose**: Deep reference, executable code, examples
|
|
|
|
## Skill Structure Requirements
|
|
|
|
### Mandatory: SKILL.md File
|
|
|
|
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
name: Your Skill Name
|
|
description: Clear description of what this does and when to use it
|
|
---
|
|
```
|
|
|
|
**Critical Constraints:**
|
|
- Name: Maximum 64 characters
|
|
- Description: Maximum 1024 characters
|
|
- **The description is crucial** - it determines when Claude triggers the skill
|
|
|
|
### Optional: Additional Resources
|
|
|
|
Structure additional files strategically:
|
|
|
|
```
|
|
my-skill/
|
|
├── SKILL.md # Main entry point (required)
|
|
├── reference.md # Deep reference material (load on-demand)
|
|
├── examples.md # Code samples and templates
|
|
├── workflows/ # Step-by-step procedures
|
|
│ ├── advanced.md
|
|
│ └── beginner.md
|
|
└── scripts/ # Executable utilities
|
|
└── helper.sh
|
|
```
|
|
|
|
## 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 for Descriptions
|
|
|
|
```
|
|
[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."
|
|
|
|
## Best Practices for SKILL.md Content
|
|
|
|
### 1. Start with "When to Use This Skill"
|
|
|
|
Immediately clarify trigger scenarios:
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
Use clear hierarchies and action-oriented headers:
|
|
|
|
```markdown
|
|
## Quick Start
|
|
[Minimal example to get started]
|
|
|
|
## Core Workflows
|
|
### Workflow 1: [Name]
|
|
1. Step one
|
|
2. Step two
|
|
|
|
### Workflow 2: [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:
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
When you need to split content, reference it clearly:
|
|
|
|
```markdown
|
|
## Deep Dive: Advanced Patterns
|
|
|
|
For comprehensive examples of [topic], 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 is 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:
|
|
1. **Tools Claude can run** without loading code into context
|
|
2. **Documentation by example** showing best practices
|
|
|
|
```markdown
|
|
## Generating Boilerplate
|
|
|
|
Run the initialization script to create project structure:
|
|
|
|
```bash
|
|
./scripts/init-project.sh my-app
|
|
```
|
|
|
|
This creates [description of what's created].
|
|
```
|
|
|
|
Claude can execute this without the 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 whether it triggers correctly:
|
|
|
|
**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 a minimal SKILL.md:
|
|
- Clear metadata
|
|
- One core workflow
|
|
- A few examples
|
|
|
|
Add complexity only when you encounter actual needs:
|
|
- Split files when SKILL.md exceeds ~3000 tokens
|
|
- Add scripts when you repeat the same commands
|
|
- Create reference files for API documentation
|
|
|
|
## Common Patterns by Domain
|
|
|
|
### Code Development Skills
|
|
|
|
```markdown
|
|
---
|
|
name: [Framework/Language] [Pattern] Guide
|
|
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
|
|
---
|
|
|
|
## When to Use This Skill
|
|
Use when building [specific project type] with [language/framework]
|
|
|
|
## Project Structure
|
|
[Standard directory layout]
|
|
|
|
## Core Workflows
|
|
### Create New [Component Type]
|
|
[Step-by-step process]
|
|
|
|
### Common Patterns
|
|
[Frequently used code patterns with examples]
|
|
|
|
## Testing Strategy
|
|
[How to test this type of code]
|
|
```
|
|
|
|
### Workflow/Process Skills
|
|
|
|
```markdown
|
|
---
|
|
name: [Task] Workflow
|
|
description: [Action] for [domain] following [methodology]. Use when [scenario].
|
|
---
|
|
|
|
## When to Use This Skill
|
|
Use when you need to [primary task] and [key differentiator]
|
|
|
|
## Prerequisites
|
|
[What's needed before starting]
|
|
|
|
## Step-by-Step Process
|
|
### Phase 1: [Name]
|
|
[Detailed steps]
|
|
|
|
### Phase 2: [Name]
|
|
[Detailed steps]
|
|
|
|
## Quality Checklist
|
|
- [ ] [Verification step]
|
|
- [ ] [Verification step]
|
|
```
|
|
|
|
### Reference/Documentation Skills
|
|
|
|
```markdown
|
|
---
|
|
name: [Topic] Reference
|
|
description: [Type of information] for [domain/tool]. Use when [looking up/configuring/understanding] [specific aspects].
|
|
---
|
|
|
|
## Quick Reference
|
|
[Most common lookups in concise format]
|
|
|
|
## Detailed Documentation
|
|
See [reference.md](reference.md) for comprehensive API documentation.
|
|
|
|
## Common Tasks
|
|
### Task 1
|
|
[Quick example]
|
|
|
|
### Task 2
|
|
[Quick example]
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### For Skill Creators
|
|
|
|
**Never include in skills:**
|
|
- 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?
|
|
|
|
### For Skill Users
|
|
|
|
**Before installing a skill:**
|
|
1. Audit all files in the skill package
|
|
2. Check for network access attempts
|
|
3. Review any bundled scripts for malicious code
|
|
4. Verify the source is trustworthy
|
|
|
|
## Debugging Skills
|
|
|
|
### Skill Doesn't Trigger
|
|
|
|
**Checklist:**
|
|
1. Is the description specific enough?
|
|
2. Does the description mention the trigger scenario?
|
|
3. Is the name too generic?
|
|
4. Test with explicit requests mentioning keywords from the description
|
|
|
|
**Example fix:**
|
|
- Before: `description: "Python development helpers"`
|
|
- After: `description: "Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems."`
|
|
|
|
### Skill Triggers Too Often
|
|
|
|
**Checklist:**
|
|
1. Is the description too broad?
|
|
2. Add negative cases: "Do NOT use for..."
|
|
3. Make the domain more specific
|
|
|
|
### Content Doesn't Load
|
|
|
|
**Checklist:**
|
|
1. Verify file paths in references are correct
|
|
2. Check that additional .md files are in the skill package
|
|
3. Ensure script paths are relative to skill root
|
|
|
|
## Skill Metadata Checklist
|
|
|
|
Before finalizing a skill, verify:
|
|
|
|
- [ ] Name is under 64 characters
|
|
- [ ] Description is under 1024 characters
|
|
- [ ] Description includes specific use cases
|
|
- [ ] Description mentions when to trigger the skill
|
|
- [ ] SKILL.md has YAML frontmatter with both fields
|
|
- [ ] "When to Use This Skill" section is present
|
|
- [ ] At least one concrete example is included
|
|
- [ ] No sensitive information is hardcoded
|
|
- [ ] File references are accurate
|
|
- [ ] Tested triggering with target scenarios
|
|
- [ ] Tested NOT triggering with related but different scenarios
|
|
|
|
## Resources
|
|
|
|
### Official Documentation
|
|
- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
|
|
- [Engineering Blog Post](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
|
- [Using Skills Guide](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
|
|
|
|
### Example Skills
|
|
Study Anthropic's pre-built skills for reference:
|
|
- Excel (xlsx) - Complex domain with many features
|
|
- Word (docx) - Document generation workflows
|
|
- PowerPoint (pptx) - Creative + structured content
|
|
- PDF (pdf) - File manipulation and analysis
|
|
|
|
## Quick Start Template
|
|
|
|
Use this template to begin a new skill:
|
|
|
|
```markdown
|
|
---
|
|
name:
|
|
description:
|
|
---
|
|
|
|
# [Skill Name]
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
-
|
|
-
|
|
|
|
Do NOT use this skill for:
|
|
-
|
|
|
|
## Quick Start
|
|
|
|
[Minimal working example]
|
|
|
|
## Core Workflows
|
|
|
|
### Workflow 1: [Name]
|
|
|
|
1.
|
|
2.
|
|
3.
|
|
|
|
**Example:**
|
|
```
|
|
[Code or command]
|
|
```
|
|
|
|
**Result:** [What this achieves]
|
|
|
|
## Common Pitfalls
|
|
|
|
### Issue: [Problem]
|
|
**Solution:** [How to avoid/fix]
|
|
|
|
### Issue: [Problem]
|
|
**Solution:** [How to avoid/fix]
|
|
|
|
## Advanced Topics
|
|
|
|
[Optional: complex scenarios or optimizations]
|
|
```
|
|
|
|
---
|
|
|
|
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.
|