| description |
|---|
Extract modules into skills AND amplify terse instructions via research into comprehensive guidance |
Extract reusable modules from instruction files (CLAUDE.md, AGENTS.md) or individual files (commands, agents, markdown) into modular skills. Additionally, identify terse instructions (e.g., "use Chrome DevTools MCP") and amplify them into comprehensive skills via web research. The original file is preserved but trimmed down with skill references, reducing context while expanding capabilities.
TARGET: $ARGUMENTS
Accepts one of:
- No arguments: Process CLAUDE.md and AGENTS.md in the current project root
- File path(s): Convert specific files (commands, agents, or any markdown)
- Example:
.claude/commands/research-codebase.md - Example:
.claude/agents/code-reviewer.md - Multiple files can be specified, space-separated
- Example:
Keep originals, extract modules, reference skills.
The goal is NOT to delete files or create 1:1 skill replacements. Instead:
- Identify self-contained modules within a file that add context bloat
- Extract those modules into separate project-local skill files
- Replace the detailed content with skill references
- Result: Original file is leaner, detailed guidance is preserved in focused skills
Amplify terse instructions into comprehensive skills.
When a file contains brief references to external tools, MCP servers, APIs, or concepts:
- Identify these "amplification candidates" - instructions that could benefit from more detail
- Research the topic using general-purpose agent with WebSearch/WebFetch
- Create comprehensive skills that go BEYOND the original instruction
- Result: Brief mentions become powerful, detailed guidance
When the target is itself a SKILL.md file, the workflow changes. Instead of extracting into separate skills, decompose the bloated SKILL.md into supporting files within the same directory.
See skill: skill-decomposition-guide for the complete decomposition workflow, including:
- Progressive Disclosure pattern and target structure
- 6-step decomposition process with plan templates
- What stays in SKILL.md vs. moves to references/examples
- Common decomposition patterns and validation checklist
Key principle: Skills should be lean (~1,500-2,000 words) with detailed content in references/, examples/, and scripts/ subdirectories.
For non-skill files, follow the standard extraction and amplification workflow below.
-
Read the target file(s) fully using Read tool (no limit/offset)
-
Identify extractable modules - look for:
- Self-contained reference material (templates, patterns, schemas)
- Detailed examples or documentation blocks
- Verbose sections that clutter the main file
- Content that would benefit from being in a dedicated, focused file
Note: For CLAUDE.md/AGENTS.md, skills are project-specific (stored in
./.claude/skills/). Don't worry about cross-project reusability—focus on reducing context size and improving organization within this project. -
Identify amplification candidates - terse instructions that reference:
- MCP servers (e.g., "use Chrome DevTools MCP", "use playwright")
- External tools or CLIs (e.g., "use gh CLI", "run shellcheck")
- APIs or services (e.g., "call the Slack API", "use OpenAI")
- Frameworks or libraries (e.g., "use Tailwind", "follow 12-factor")
- Concepts that deserve deeper guidance (e.g., "handle errors properly")
-
Identify what should stay inline:
- Core workflow steps specific to this command
- Decision logic unique to this use case
- Brief summaries and orchestration
See skill: skillify-decision-guide for detailed extraction/amplification criteria.
For each extractable module:
EXTRACTION: "[Section/Block Name]"
Skill Name: [kebab-case-name]
Lines in Original: [approximate]
Context Reduction: [how much leaner does original become?]
Description: [trigger-focused description for skill frontmatter]
For each amplification candidate:
AMPLIFICATION: "[Terse Instruction]"
Skill Name: [kebab-case-name]
Current Detail: [1-2 lines / brief mention / etc.]
Research Topics: [what to look up - docs, best practices, examples]
Value Add: [what comprehensive skill would provide]
Description: [trigger-focused description for skill frontmatter]
Present the plan to the user before proceeding.
For each amplification candidate, spawn a general-purpose agent to research:
See skill: task-agent-patterns for agent spawning patterns and prompt best practices.
Task tool:
subagent_type: general-purpose
prompt: "Research [topic] for creating a comprehensive skill. Use WebSearch
to find documentation and guides, then WebFetch to read key pages. Include:
- Official documentation and getting started guides
- Key concepts and terminology
- Common use cases and examples
- Best practices and gotchas
- Configuration options and parameters
- Error handling patterns
- Integration patterns with Claude Code / AI assistants
Return a comprehensive summary suitable for creating a skill file."
Research depth guidance:
- MCP servers: Focus on available tools, when to use each, common patterns
- CLI tools: Focus on flags, common workflows, output parsing
- APIs: Focus on authentication, key endpoints, rate limits, error handling
- Frameworks: Focus on core concepts, project structure, conventions
Compile research findings before creating skills.
For each module (extraction) and research result (amplification), create a skill.
See skill: skill-structure-guide for complete SKILL.md format and best practices.
Directory structure (project-local):
./.claude/skills/[skill-name]/
└── SKILL.md
Skills are created in the current project's .claude/skills/ directory, making them project-specific. This is intentional—focus on reducing context size rather than cross-project reusability.
Guidelines for extracted skills:
- Keep under 500 lines
- Use imperative form
- Include examples where helpful
- Can assume project context (these are project-specific skills)
Guidelines for amplified skills:
- Go BEYOND the original instruction - add real value
- Include practical examples specific to Claude Code context
- Document tool parameters, options, and common patterns
- Add troubleshooting guidance and common pitfalls
- Include "when to use" and "when NOT to use" guidance
- Keep actionable - not just reference docs, but how to actually use it
Replace extracted sections with skill references:
Before (verbose):
## Document Template
### File Naming Convention
Location: `thoughts/shared/research/`
Format: `YYYY-MM-DD-description.md`
...
[45 more lines of template details]After (lean):
## Document Template
**See skill: `research-document-template`** for structure and metadata.
Write to `thoughts/shared/research/YYYY-MM-DD-description.md`Guidelines:
- Keep 1-2 sentence summary of what the skill provides
- Include the skill reference clearly
- Keep any context-specific details inline
See skill: skillify-examples for report format and additional examples.
Generate a summary showing:
- Extraction results (before/after line counts, reduction %)
- Skills created (extracted and amplified)
- Skill references added
- Next steps for verification
- Use kebab-case:
explore-agent-patterns - Be descriptive:
research-document-templatenottemplate - Indicate scope:
bash-agent-patternsnotbash