claude-plugins/claude-code/skills/claude-skills/SKILL.md

---
name: Skill Creator
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY BEFORE starting skill creation to review best practices, DURING skill structuring to optimize content organization, AFTER completing a skill draft to validate triggers and structure, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills.
---

# 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
- Optimizing skill structure for token efficiency
- Before, during, and after skill creation

## Core Principle: Progressive Disclosure

**The fundamental design pattern for Agent Skills.**

### Three Layers

1. **Metadata** (Always Loaded ~100 tokens)
   - YAML frontmatter: `name` and `description`
   - Triggers skill activation

2. **Instructions** (Triggered ~800-1000 tokens)
   - Main SKILL.md content
   - Workflows and guidance

3. **Resources** (On-Demand)
   - Additional files loaded when needed
   - Examples, reference docs, scripts

## Skill Structure Requirements

### Mandatory: SKILL.md

```yaml
---
name: Your Skill Name                          # Max 64 chars
description: What it does and when to use it   # Max 1024 chars
---
```

**Critical**: The description determines when Claude triggers the skill.

### Optional: Additional Files

```
my-skill/
├── SKILL.md                 # Required entry point
├── examples.md              # Working code samples
├── reference.md             # Deep API docs
└── workflows/
    ├── beginner.md
    └── advanced.md
```

## Writing Effective Descriptions

The `description` is your trigger mechanism.

### Template
```
[Action] [domain/task] [with capabilities].
Use when [trigger scenario]. PROACTIVELY when [context].
```

### Examples

**✓ Good**:
```yaml
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building reports or data analysis.

description: Debug Swift applications using LLDB for crashes, memory issues, and runtime errors. Use PROACTIVELY when encountering Swift bugs.
```

**✗ Poor**:
```yaml
description: Helps with coding
description: Python utilities
description: Security checker
```

## Essential SKILL.md Structure

### 1. When to Use This Skill

```markdown
## When to Use This Skill

Use this skill when:
- [Primary scenario]
- [Secondary scenario]

Do NOT use this skill for:
- [Common confusion]
- [Different tool]
```

### 2. Quick Start

```markdown
## Quick Start

Minimal working example:

```[language]
[code]
```

**Result**: [What this achieves]
```

### 3. Core Workflows

```markdown
## Core Workflows

### Workflow 1: [Name]

1. [Step]
2. [Step]
3. [Step]

**Example**:
```[language]
[code]
```
```

### 4. Additional Resources

```markdown
## Additional Resources

**Need more?**
- [Examples](examples.md) - Working code samples
- [Reference](reference.md) - API documentation
- [Advanced Workflows](workflows/advanced.md)

💡 **Tip**: These load only when referenced.
```

## Token Optimization

### Target Sizes
- SKILL.md: 800-1000 tokens (~200-250 lines)
- Supplementary files: As needed

### When to Split

**Keep in SKILL.md**:
- Needed 80%+ of time
- Under 1000 tokens
- Sequential steps

**Move to separate file**:
- Mutually exclusive content
- Reference material
- Advanced/edge cases

### Compression Techniques

1. **Bullet points > Paragraphs** (50% more efficient)
2. **Code examples > Prose** (show don't tell)
3. **References > Embedding** (load on-demand)
4. **Concrete > Abstract** (examples beat theory)

## Development Workflow

### 1. Identify Need

Don't guess - observe:
1. Run Claude on representative tasks
2. Find repeated questions or struggles
3. Capture successful patterns
4. Codify into skill

### 2. Start Minimal

```yaml
---
name: My Skill
description: [Specific, clear trigger description]
---

## When to Use This Skill
[Clear scenarios]

## Quick Start
[One minimal example]

## Core Workflow
[3-5 essential steps]
```

### 3. Test Triggering

**Positive tests** (should activate):
- "Create X using Y"
- "[Domain-specific request]"

**Negative tests** (should NOT activate):
- "[Related but different domain]"
- "[Different tool's purpose]"

### 4. Grow Organically

Add only when needed:
- More examples from actual usage
- Advanced workflows when requested
- Reference docs when API is complex
- Scripts for repeated commands

## Common Patterns by Domain

### Code Development Skills

```markdown
---
name: [Framework] [Pattern] Guide
description: [Action] [framework] applications following [pattern]. Use when building [type] with [requirements].
---

## When to Use This Skill
[Specific project types]

## Project Structure
[Standard layout]

## Core Workflows
### Create [Component]
[Steps]

## Testing Strategy
[How to test]
```

### Workflow Skills

```markdown
---
name: [Task] Workflow
description: [Action] for [domain] following [methodology]. Use when [scenario].
---

## Prerequisites
[What's needed]

## Step-by-Step Process
### Phase 1: [Name]
[Steps]

## Quality Checklist
- [ ] [Verification]
```

## Debugging Skills

### Skill Doesn't Trigger

**Fix description**:
```yaml
# ❌ Too vague
description: Python development helpers

# ✓ Specific with triggers
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

**Add negatives**:
```markdown
## When to Use This Skill

Use when:
- [Specific scenario]

Do NOT use for:
- [Broader scenario that should use different skill]
```

### Content Doesn't Load

**Check references**:
- Verify file paths are correct
- Ensure .md files exist in skill directory
- Use relative paths from skill root

## Skill Checklist

Before finalizing:

- [ ] Name under 64 characters
- [ ] Description under 1024 characters, includes triggers
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references work
- [ ] Tested positive trigger scenarios
- [ ] Tested negative scenarios (doesn't over-trigger)
- [ ] Size under 1000 tokens for SKILL.md

## Quick Start Template

```markdown
---
name: [Skill Name]
description: [Action] [domain] [with capabilities]. Use when [scenario]. PROACTIVELY when [context].
---

# [Skill Name]

## When to Use This Skill

Use this skill when:
- [Primary scenario]
- [Secondary scenario]

Do NOT use this skill for:
- [Common confusion]

## Quick Start

[Minimal working example]

## Core Workflows

### Workflow 1: [Name]

1. [Step]
2. [Step]
3. [Step]

**Example**:
```
[code]
```

**Result**: [What this achieves]

## Common Pitfalls

### Issue: [Problem]
**Solution**: [Fix]

## Additional Resources

**Need more?**
- [Examples](examples.md) - Working samples
- [Reference](reference.md) - API docs
- [Advanced](workflows/advanced.md) - Complex patterns

💡 **Tip**: [Key insight]
```

## Additional Resources

**Need more?**
- [Skill Examples](examples.md) - Complete working skills
- [Best Practices Guide](best-practices.md) - Comprehensive guidelines
- [Templates](templates.md) - Ready-to-use templates
- [Checklist](checklist.md) - Validation checklist
- [Official Docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)

💡 **Tip**: Best skills emerge from real usage. Start simple, iterate based on actual needs, prioritize clarity over comprehensiveness.

---

**Remember**: Specific descriptions trigger correctly. Progressive disclosure saves tokens. Test thoroughly. Start minimal and grow organically.