skillify

What this skill does

# Skillify

Extract reusable modules from instruction files into skills. Also amplify terse instructions (e.g., "use Chrome DevTools MCP") into comprehensive skills via web research. The original file is preserved but trimmed down with skill references.

## Core Principles

1. **Keep originals, extract modules, reference skills** - Don't delete files; extract bloated sections into focused skills, then reference them
2. **Amplify terse instructions** - Brief "use X" mentions become comprehensive guidance through research
3. **Project-local skills** - Skills go in `./.claude/skills/`, focused on reducing context rather than cross-project reuse

## Arguments

**TARGET**: `$ARGUMENTS`

- **No arguments**: Process CLAUDE.md and AGENTS.md in project root
- **File path(s)**: Specific files to process (space-separated)

## Edge Case: Skillifying a SKILL.md

When target is itself a SKILL.md file, **decompose into supporting files** within the same directory instead of extracting to separate skills.

**See `references/skill-decomposition-guide.md`** for the complete decomposition workflow.

---

## Standard Workflow

For commands, agents, CLAUDE.md files - follow this 6-step process.

### Step 0: Create Task List

Create all 6 tasks upfront for visibility. **See `references/task-orchestration-patterns.md`** for the pattern.

```
TaskCreate(subject="Analyze target files", activeForm="Analyzing files")
TaskCreate(subject="Plan extraction & amplification", activeForm="Planning")
TaskCreate(subject="Research amplifications", activeForm="Researching")
TaskCreate(subject="Create skills", activeForm="Creating skills")
TaskCreate(subject="Update original files", activeForm="Updating files")
TaskCreate(subject="Generate summary report", activeForm="Generating report")
```

### Step 1: Read and Analyze

1. **Read target file(s)** fully
2. **Identify extractable modules** - self-contained reference material, templates, patterns, verbose sections (>30 lines)
3. **Identify amplification candidates** - terse references to MCP servers, external tools, APIs, frameworks
4. **Identify what stays inline** - core workflow, decision logic, brief summaries

**See `references/skillify-decision-guide.md`** for extraction/amplification criteria.

### Step 2: Plan Extraction & Amplification

**For each extractable module:**
```
EXTRACTION: "[Section Name]"
  Skill Name: [kebab-case-name]
  Lines in Original: [N]
  Context Reduction: [how much leaner?]
  Description: [trigger-focused description]
```

**For each amplification candidate:**
```
AMPLIFICATION: "[Terse Instruction]"
  Skill Name: [kebab-case-name]
  Current Detail: [1-2 lines]
  Research Topics: [what to look up]
  Value Add: [what comprehensive skill provides]
```

Present plan before proceeding.

### Step 3: Research Amplification Candidates

**CRITICAL: Spawn ALL research agents in ONE message for parallel execution.**

**See `references/task-agent-patterns.md`** for agent spawning patterns.

```
Task(
  subagent_type="general-purpose",
  model="haiku",
  description="Research [topic]",
  prompt="Research [topic] for creating a comprehensive skill. Use WebSearch
    to find documentation. Include:
    - Official documentation
    - Key concepts and terminology
    - Common use cases and examples
    - Best practices and gotchas
    - Configuration options
    - Error handling patterns
    Return a comprehensive summary suitable for creating a skill file."
)
// ... one agent per amplification candidate
```

**Wait for ALL agents to complete** before proceeding.

### Step 4: Create Skills

**See `references/skill-structure-guide.md`** for SKILL.md format.

**Directory structure:**
```
./.claude/skills/[skill-name]/
└── SKILL.md
```

**Guidelines for extracted skills:**
- Keep under 500 lines
- Use imperative form
- Include examples where helpful

**Guidelines for amplified skills:**
- Go BEYOND the original instruction
- Include practical examples
- Document tool parameters and options
- Add troubleshooting guidance
- Include "when to use" and "when NOT to use"

### Step 5: Update Original File

Replace extracted sections with skill references:

**Before:**
```markdown
## Document Template

### File Naming Convention
Location: `thoughts/shared/research/`
Format: `YYYY-MM-DD-description.md`
...
[45 more lines]
```

**After:**
```markdown
## Document Template

**See skill: `research-document-template`** for structure and metadata.

Write to `thoughts/shared/research/YYYY-MM-DD-description.md`
```

### Step 6: Summary Report

**See `references/skillify-examples.md`** for report format.

Generate summary showing:
- Extraction results (before/after line counts, reduction %)
- Skills created (extracted and amplified)
- Skill references added

## Key Rules

| Rule | Reason |
|------|--------|
| Create all tasks upfront | Shows full scope |
| ALL Task calls in ONE message | Enables parallel execution |
| Wait for ALL agents before proceeding | Gather all results first |
| Subagents can't spawn subagents | All Task() calls from main level |

## Skill Naming

- Use **kebab-case**: `explore-agent-patterns`
- Be **descriptive**: `research-document-template` not `template`
- **Indicate scope**: `bash-agent-patterns` not `bash`

## Additional Resources

### Reference Files
- **`references/skill-decomposition-guide.md`** - Decomposing bloated SKILL.md files
- **`references/skillify-decision-guide.md`** - Extraction vs amplification criteria
- **`references/task-orchestration-patterns.md`** - Task tracking patterns for commands
- **`references/task-agent-patterns.md`** - Agent spawning and prompt patterns
- **`references/skill-structure-guide.md`** - SKILL.md format and best practices
- **`references/skillify-examples.md`** - Example extractions and report format