claude-plugins/claude-code/skills/claude-skills/best-practices.md

# 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 `name` and `description`
- **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

```yaml
---
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"

```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

```markdown
## 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:

```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

```markdown
## 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:
1. **Tools Claude can run** without loading code into context
2. **Documentation by example** showing best practices

```markdown
## 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
```markdown
You are a code reviewer. Review code.
```
**Fix**: Define step-by-step process

### ❌ All Tools Granted
```yaml
# Omitting tools when only reads needed
```
**Fix**: Whitelist minimum required tools

### ❌ Verbose Prompt
```markdown
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

```markdown
# 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:**

1. **Write specific descriptions** with clear triggers
2. **Structure progressively** (metadata → core → details)
3. **Start simple** and grow based on actual needs
4. **Test thoroughly** with positive and negative scenarios
5. **Optimize tokens** by splitting appropriately
6. **Provide examples** not just theory
7. **Monitor usage** and refine based on feedback