---
name: skillify-decision-guide
description: |
  Decision criteria for when to extract content into skills vs keep inline,
  and when to amplify terse instructions via research. Use this skill when
  running /skillify, when deciding what makes a good extraction candidate,
  or when evaluating amplification opportunities. Triggers: "should I extract",
  "extraction criteria", "amplification criteria", "what to keep inline",
  "skillify decision", "good extraction candidate".
---

# Skillify Decision Guide

Criteria for extraction, amplification, and inline retention decisions.

## Extraction Criteria

### Extract When:
- Content is **self-contained and reusable** - doesn't depend on surrounding context
- **Multiple commands/agents could benefit** from the same guidance
- Section is **>30 lines** of detailed guidance
- Content is **reference material** (templates, patterns, tables, schemas)
- Content represents **established best practices** worth standardizing

### Keep Inline When:
- Content is **<20 lines** - extraction overhead not worth it
- Content is **specific to this one file's purpose** - not generalizable
- Content is **orchestration/workflow logic** - the "how" of this particular command
- Content involves **context-dependent decisions** - requires knowledge of the surrounding flow
- Content is a **brief summary** that just introduces a concept

### Extraction Sizing Guide

| Lines | Recommendation |
|-------|----------------|
| <20 | Keep inline |
| 20-30 | Consider if highly reusable |
| 30-50 | Good extraction candidate |
| 50-100 | Strong extraction candidate |
| >100 | Definitely extract, may need to split |

## Amplification Criteria

### Amplify When:
- Instruction references **external tool/service without usage details**
- **"Use X" assumes knowledge** the reader may not have
- **MCP server mentioned** without explaining available tools
- **API/CLI referenced** without common patterns or examples
- **Concept mentioned** that has established best practices worth documenting
- Research would yield **>50 lines of actionable guidance**

### Skip Amplification When:
- The tool/concept is **trivially simple** (e.g., "use cat to read files")
- **Comprehensive skill already exists** for this topic
- The instruction is **intentionally brief** - user should look it up themselves
- Research would yield **minimal additional value** (<30 lines)
- The topic is **too niche** - only relevant to this one use case

### Amplification Value Indicators

| Indicator | Amplify? | Reason |
|-----------|----------|--------|
| "Use X MCP" | Yes | MCP servers have many tools to document |
| "Run shellcheck" | Maybe | Has flags, but fairly straightforward |
| "Use Git" | No | Too broad, many existing resources |
| "Follow 12-factor" | Yes | Complex methodology worth summarizing |
| "Call the API" | Yes | Auth, endpoints, errors need documenting |

## Amplification Value-Add Checklist

Good amplification adds value by:
- [ ] Turning "use X" into "here's how to use X effectively"
- [ ] Documenting tool options the original author may not have known
- [ ] Adding troubleshooting guidance from real-world experience
- [ ] Providing decision frameworks (when to use tool A vs B)
- [ ] Including integration patterns specific to Claude Code workflows
- [ ] Adding "when NOT to use" guidance to prevent misuse

## Quick Decision Flowchart

```
Is content >30 lines?
├─ No → Keep inline (unless highly reusable)
└─ Yes → Is it self-contained?
         ├─ No → Keep inline (context-dependent)
         └─ Yes → Is it reusable elsewhere?
                  ├─ No → Keep inline (too specific)
                  └─ Yes → EXTRACT

Is instruction terse (<5 lines)?
├─ No → Not an amplification candidate
└─ Yes → Does it reference external tool/service?
         ├─ No → Not an amplification candidate
         └─ Yes → Would research add >50 lines of value?
                  ├─ No → Skip amplification
                  └─ Yes → AMPLIFY
```

## Examples by Content Type

| Content Type | Typical Decision | Reason |
|--------------|------------------|--------|
| Templates | Extract | Highly reusable, self-contained |
| Workflow steps | Keep inline | Specific to this command |
| Tool reference tables | Extract | Reference material, reusable |
| Decision logic | Keep inline | Context-dependent |
| Best practices (>30 lines) | Extract | Reusable guidance |
| MCP server mentions | Amplify | Need tool documentation |
| API references | Amplify | Need auth/endpoint details |
| Brief tips (<10 lines) | Keep inline | Too small for skill |

## Naming Extracted/Amplified Skills

- Use **kebab-case**: `explore-agent-patterns`
- Be **descriptive**: `research-document-template` not `template`
- **Indicate scope**: `bash-agent-patterns` not `bash`
- Include **domain context**: `skillify-decision-guide` not `decision-guide`