---
name: Skills Creation
description: |
  Guide for creating, structuring, and maintaining Claude skills.
  Skills are reusable instruction sets with progressive disclosure.

  WHEN TO USE:
  - "Create a new skill"
  - "How to make Claude skills"
  - "Package this as a skill"
  - "Skills best practices"
  - Packaging workflows as skills
  - Extending official skills
  - Building domain expertise skills

  CAPABILITIES:
  - Skill structure and format
  - Progressive disclosure design
  - Trigger phrase optimization
  - Script integration patterns

allowed-tools:
  - Read
  - Write
---

# Skills Creation

## Purpose

Skills are reusable instruction sets that teach Claude how to perform specific tasks. They're more than documentation - they're executable expertise with progressive disclosure.

## Why Skills?

```
Before Skills:           After Skills:
─────────────────        ─────────────────
Repeat instructions      Define once, use everywhere
Inconsistent execution   Consistent behavior
Context bloat            Progressive disclosure
Session-limited          Persistent across sessions
```

## Skill Structure

```
.claude/skills/[skill-name]/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: Python tools
│   └── helper.py
├── references/           # Optional: detailed docs (lazy-loaded)
│   └── full_guide.md
└── examples/             # Optional: sample usage
    └── demo.md
```

## SKILL.md Format

```yaml
---
name: Human-Friendly Name    # Title Case, not kebab-case
description: |
  Brief summary of what skill does.

  WHEN TO USE:
  - "Trigger phrase 1"
  - "Trigger phrase 2"
  - "Trigger phrase 3"
  - Description of when to activate

  CAPABILITIES:
  - What it can do #1
  - What it can do #2

allowed-tools:              # Minimal set needed
  - Read
  - Write
---

# Skill Name

## Purpose
Clear statement of purpose.

## Instructions
### Step 1: [Action]
Details...

### Step 2: [Action]
Details...

## Scripts
List scripts with descriptions.

## References
See references/ for more.
```

## Progressive Disclosure

**Key Insight**: Only name + description load at startup.

```
LOADING SEQUENCE:

1. Frontmatter (always loaded)
   └── ~200-500 tokens
   └── Claude uses description to decide activation

2. SKILL.md body (on trigger)
   └── ~500-2000 tokens
   └── Contains instructions

3. scripts/ (on demand)
   └── Called when operation needed

4. references/ (on demand)
   └── Only when context needed
   └── Can be large
```

## Writing Good Descriptions

**Bad**: Vague, Claude won't activate
```yaml
description: Helps with tasks
```

**Good**: Specific triggers
```yaml
description: |
  Implements PITER framework for autonomous agent workflows.

  WHEN TO USE:
  - "Run PITER on this task"
  - "Create an AFK agent"
  - "Build autonomous workflow"
  - Need agent to work without supervision
```

## Three Ways to Create Skills

### 1. Extend Official Skills
```
Take existing skill → Add your customization

Example:
- Start with "PowerPoint Building" skill
- Add your brand template
- Create "Branded Deck" skill that references parent
```

### 2. Package Existing Workflow
```
Project instructions → Skill format

Example:
- You have project with custom instructions
- Extract into SKILL.md
- Now portable across projects
```

### 3. Create from Scratch with MCP
```
MCP tools → Skill wrapper

Example:
- Ahrefs MCP has many tools
- Create "Keyword Research" skill
- Only loads relevant MCP tools
```

## When to Create a Skill

Ask yourself:
1. Do you repeat same instructions 3+ times?
2. Would you train a human on this process?
3. Is consistency needed every time?

**If 2+ YES → Create a skill**

## Script Integration

```python
# scripts/helper.py
#!/usr/bin/env python3
"""Helper for skill operations"""

def process(input_data):
    """Process input deterministically"""
    # Deterministic = same input always gives same output
    # Don't rely on LLM for this
    return transformed_data

if __name__ == "__main__":
    import sys
    result = process(sys.argv[1])
    print(result)
```

## Skills vs Alternatives

| Feature | Skills | Projects | MCPs |
|---------|--------|----------|------|
| Loading | Progressive | Full | Full tools |
| Scope | Global | Per-project | System |
| Purpose | Instructions | Workspace | Capabilities |
| Tokens | ~500-2000 | Varies | ~2000+ |

## Best Practices

1. **One Skill = One Expertise**
   - Don't overload skills
   - Clear, focused purpose

2. **Optimize Descriptions**
   - Be specific about triggers
   - This is how Claude decides

3. **Minimize allowed-tools**
   - Only what's needed
   - Principle of least privilege

4. **Use references/ for Depth**
   - Keep SKILL.md lean
   - Details in references/

5. **Test Activation**
   - Say trigger phrases
   - Verify skill activates

## Skill Maintenance

Skills are static - update when:
- MCP tool functions change
- Better patterns discovered
- Requirements evolve

```python
# Add backup plan in skill
"""
If primary approach fails:
1. Try alternative method
2. Fall back to manual steps
3. Report for human review
"""
```

## References

See `references/` for examples and templates.
