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 ~50): [OK count], [WARNING count]
- Tier 2 (SKILL.md ~500): [OK count], [WARNING count], [CRITICAL count]
- Tier 3 (References 2000+ typical): [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]