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