---
name: skill-decomposition-guide
description: |
  Guide for decomposing large SKILL.md files into lean core + supporting files.
  Use this skill when refactoring bloated skills, splitting skill content into
  references/examples directories, or applying Progressive Disclosure pattern.
  Triggers: "decompose skill", "split SKILL.md", "skill too large",
  "progressive disclosure", "lean skill", "skill references directory",
  "skillify a skill", "break up skill file".
---

# Skill Decomposition Guide

Decompose bloated SKILL.md files into lean core instructions + supporting files, following the Progressive Disclosure pattern.

## When to Use

- SKILL.md exceeds ~3,000 words or ~500 lines
- Skill loads unnecessary detail into context
- Want to enable on-demand loading of reference material
- Refactoring existing skills for better organization

## Progressive Disclosure Principle

Skills use a three-level loading system:

1. **Metadata** (always in context): `name` + `description` (~100 words)
2. **SKILL.md body** (when skill triggers): Core workflow (<2,000 words)
3. **Supporting files** (loaded as needed): Unlimited depth

A bloated SKILL.md wastes context. Breaking it into supporting files lets the AI agent load detail on-demand.

## Target Directory Structure

```
skill-name/
├── SKILL.md              # Lean: core workflow, pointers (~1,500-2,000 words)
├── references/           # Detailed docs, patterns, advanced techniques
│   ├── patterns.md
│   ├── advanced.md
│   └── api-reference.md
├── examples/             # Working code, templates, configurations
│   ├── basic-example.md
│   └── advanced-example.md
└── scripts/              # Executable utilities (if applicable)
    └── validate.sh
```

## Decomposition Workflow

### Step 1: Analyze the SKILL.md

Read the skill and categorize content:

| Category | Destination | Content Type |
|----------|-------------|--------------|
| Core | SKILL.md | Purpose, when to use, essential workflow, resource pointers |
| Reference | `references/` | Detailed patterns, advanced techniques, API docs, troubleshooting |
| Examples | `examples/` | Code samples, templates, working configurations |
| Scripts | `scripts/` | Validation tools, utilities |

### Step 2: Plan the Decomposition

```
SKILL DECOMPOSITION: "[skill-name]"
  Current Lines: [X]
  Target SKILL.md: ~[Y] lines (1,500-2,000 words)

  KEEP IN SKILL.md:
  - [Section name] (essential workflow)
  - [Section name] (core concepts)

  MOVE TO references/:
  - "[Section]" → references/patterns.md (~Z lines)
  - "[Section]" → references/advanced.md (~Z lines)

  MOVE TO examples/:
  - "[Code block]" → examples/basic-example.md
  - "[Template]" → examples/template.md
```

Present plan before proceeding.

### Step 3: Create Supporting Files

```bash
mkdir -p skill-name/references skill-name/examples
```

For each extracted section:
- Write standalone file with clear heading
- Include enough context to be useful without SKILL.md
- Keep logical groupings (all patterns together, all examples together)

### Step 4: Update SKILL.md

Replace extracted sections with pointers.

**Before (bloated):**
```markdown
## Advanced Patterns

### Pattern 1: Complex Workflow
[200 lines of detailed pattern explanation]

### Pattern 2: Error Handling
[150 lines of error handling patterns]
```

**After (lean):**
```markdown
## Advanced Patterns

For detailed patterns, see `references/patterns.md`:
- Complex Workflow pattern
- Error Handling pattern
- Integration patterns

Use these when implementing production features.
```

### Step 5: Add Resources Section

Ensure SKILL.md references all supporting files:

```markdown
## Additional Resources

### Reference Files
- **`references/patterns.md`** - Detailed implementation patterns
- **`references/advanced.md`** - Advanced techniques and edge cases

### Examples
- **`examples/basic-example.md`** - Getting started example
- **`examples/advanced-example.md`** - Production-ready example
```

### Step 6: Summary Report

```
SKILL DECOMPOSITION COMPLETE: [skill-name]

Before: [X] lines in SKILL.md
After:  [Y] lines in SKILL.md ([Z]% reduction)

Files Created:
- references/patterns.md ([N] lines)
- references/advanced.md ([N] lines)
- examples/basic-example.md ([N] lines)

Progressive Disclosure levels:
- Level 1: Metadata (always loaded)
- Level 2: SKILL.md body (on trigger)
- Level 3: references/examples (on demand)
```

## What Stays in SKILL.md

- Purpose and "when to use" guidance
- Essential workflow steps (high-level)
- Quick reference tables
- Pointers to supporting files
- Most common use cases

**Target: 1,500-2,000 words**

## What Moves to references/

- Detailed patterns and advanced techniques
- Comprehensive API documentation
- Migration guides
- Edge cases and troubleshooting
- Extensive explanations

**Each file: 500-2,000+ words**

## What Moves to examples/

- Complete, runnable code
- Configuration files
- Template files
- Real-world usage examples

**Users copy and adapt these directly**

## Common Decomposition Patterns

### Pattern: Single Large Section

One section dominates the skill.

```
SKILL.md (800 lines)
└── "API Reference" section (600 lines)

→ Move to references/api-reference.md
→ Keep 5-line summary + pointer in SKILL.md
```

### Pattern: Multiple Detailed Sections

Several sections each have significant detail.

```
SKILL.md (1200 lines)
├── "Patterns" (300 lines)
├── "Advanced" (250 lines)
└── "Troubleshooting" (200 lines)

→ references/patterns.md
→ references/advanced.md
→ references/troubleshooting.md
→ SKILL.md keeps summaries + pointers (~450 lines)
```

### Pattern: Code-Heavy Skill

Many inline code examples.

```
SKILL.md (900 lines)
├── Inline examples throughout (400 lines of code)

→ examples/basic.md (simple examples)
→ examples/advanced.md (complex examples)
→ SKILL.md references examples, keeps 1-2 minimal inline
```

## Validation Checklist

After decomposition, verify:

- [ ] SKILL.md under 2,000 words
- [ ] All referenced files exist
- [ ] Each supporting file is standalone (useful without SKILL.md)
- [ ] "Additional Resources" section lists all files
- [ ] No duplicate content between SKILL.md and references
- [ ] Logical grouping in each reference file