| name | optimize-plugin |
| description | This skill should be used when the user asks to "validate a plugin", "optimize plugin", "check plugin quality", "review plugin structure", or "run plugin optimizer". |
| argument-hint | <plugin-path> |
| user-invocable | true |
| allowed-tools | ["Read","Glob","Bash(realpath:*)","Bash(python3:*)","AskUserQuestion","TaskCreate","TaskUpdate","Skill","Task"] |
Plugin Optimization
Execute plugin validation and optimization workflow. Target: $ARGUMENTS
Background Knowledge
Load plugin-optimizer:plugin-best-practices skill using the Skill tool for component templates, tool invocation rules, and type classification.
Phase 1: Discovery & Validation
Goal: Validate structure and detect issues. Orchestrator MUST NOT apply fixes.
Actions:
- Resolve path with
realpath and verify existence
- Validate
.claude-plugin/plugin.json exists
- Find component directories:
commands/, agents/, skills/, hooks/
- Validate components against
${CLAUDE_PLUGIN_ROOT}/examples/ templates
- Assess architecture: if
commands/ exists with .md files, use AskUserQuestion tool to ask about migrating to skills structure
- Run validation:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"
- Options:
--check=structure,manifest,frontmatter,tools,tokens
- JSON output:
--json
- Verbose:
-v, --verbose
- Compile issues by severity (Critical, Warning, Info)
Phase 2: Agent-Based Optimization
Goal: Launch agent to apply ALL fixes. Orchestrator does NOT make fixes directly.
Condition: Always execute.
Actions:
- Launch
plugin-optimizer:plugin-optimizer agent with the following prompt content:
- Target plugin path (absolute path from Phase 1)
- Validation console output (issues list from Phase 1)
- Template validation results
- User decisions (migration choice if applicable)
- INSTRUCTION: Analyze the validation output to identify issues
- Agent autonomously applies fixes (MUST use
AskUserQuestion tool before applying template fixes, presenting violations with specific examples and before/after comparison)
- Agent increments version in
.claude-plugin/plugin.json after fixes:
- Patch (x.y.Z+1): Bug fixes
- Minor (x.Y+1.0): New components
- Major (X+1.0.0): Breaking changes
- Wait for agent to complete
Path Reference Rules:
- Same directory: Use relative paths (
./reference.md)
- Outside directory: Use
${CLAUDE_PLUGIN_ROOT} paths
- Component templates: See
${CLAUDE_PLUGIN_ROOT}/examples/
Redundancy & Efficiency:
- Redundancy: Allow strategic repetition of critical content (MUST/SHOULD requirements). Favor concise restatement.
- Efficiency: Agent detects if tasks need Agent Teams (Parallelizable > 5 files, Multi-domain).
Phase 3: Verification & Deliverables
Goal: Verify fixes, generate report, and update documentation.
Actions:
- Execute validation script:
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"
- Analyze results: compare with Phase 1 findings, confirm critical issues resolved
- If critical issues remain, resume agent execution
- Generate final validation report using template below
- Update
README.md to reflect current state (metadata, directory structure, usage instructions; do not append version history log)
Validation Report Template
## Plugin Validation Report
### Plugin: [name]
Location: [absolute-path]
Version: [old] -> [new]
### Summary
[2-3 sentences with key statistics]
### Phase 1: Issues Detected
#### Critical ([count])
- `file/path` - [Issue description]
#### Warnings ([count])
- `file/path` - [Issue description]
### Phase 2: Fixes Applied
#### Structure Fixes
- [Fix description]
#### Template Conformance
- **Agents**: [Count] validated, [count] fixed
- **Instruction-type Skills**: [Count] validated, [count] fixed
- **Knowledge-type Skills**: [Count] validated, [count] fixed
#### Redundancy Fixes
- [Consolidations applied]
### Phase 3: Verification Results
- Structure validation: [PASS/FAIL]
- Manifest validation: [PASS/FAIL]
- Component validation: [PASS/FAIL]
- Tool patterns validation: [PASS/FAIL]
- Token budgets validation: [PASS/FAIL]
### Token Budget Analysis
- Skills analyzed: [count]
- Tier 1 (Metadata ~100): [OK count], [WARNING count]
- Tier 2 (SKILL.md under 5k): [OK count], [WARNING count], [CRITICAL count]
- Tier 3 (References, effectively unlimited): [total tokens]
### Component Inventory
- Commands: [count] found, [count] valid
- Agents: [count] found, [count] valid
- Skills: [count] found, [count] valid
### Remaining Issues
[Issues that couldn't be auto-fixed with explanations]
### Overall Assessment
[PASS/FAIL] - [Detailed reasoning]
