| name | refactoring-plugins |
| description | Refactors and audits Claude Code plugin packages against official best practices. Use when refactoring, migrating, or auditing a Claude Code plugin package. Use when user says "refactor plugin", "audit plugin", "plugin health check", "migrate plugin structure". Use when plugin structure drifts from official best practices. |
Refactoring Plugins
Overview
Refactoring plugins IS aligning plugin structure with official Claude Code best practices.
Run health checks, detect structural drift, fix anti-patterns, and verify the result. Plugins differ from agent systems — they have an official schema (plugin.json), auto-discovery conventions, and distribution requirements.
Core principle: A plugin that fails health check will fail in production. Measure first, then fix.
Task Initialization (MANDATORY)
Follow task initialization protocol.
Tasks:
- Identify plugin target
- Run health check
- Analyze findings against checklist
- Present refactoring plan
- Execute refactoring
- Verify fixes
- Verify version bump documentation in plugin CLAUDE.md
Announce: "Created 7 tasks. Starting execution..."
Task 1: Identify Plugin Target
Goal: Locate the plugin to refactor.
Discovery order:
- User provided a path → use it
- Current directory has
.claude-plugin/plugin.json → use it
- Search for
*/.claude-plugin/plugin.json in working directory
- Ask user to specify
Record:
- Plugin root path
- Plugin name (from plugin.json or directory name)
- Whether a marketplace.json exists upstream
Verification: Have a valid plugin directory with .claude-plugin/plugin.json.
Task 2: Run Health Check
Goal: Execute the automated health check script.
Step 1: Run claude plugin validate <plugin-path> (official CLI).
Step 2: Run extended health check (bash-first, three-runner fallback with brace grouping):
{ command -v uv >/dev/null 2>&1 && uv run "${CLAUDE_SKILL_DIR}/scripts/validate_plugin.py" <plugin-path>; } \
|| { python3 --version >/dev/null 2>&1 && python3 "${CLAUDE_SKILL_DIR}/scripts/validate_plugin.py" <plugin-path>; } \
|| python "${CLAUDE_SKILL_DIR}/scripts/validate_plugin.py" <plugin-path>
The script integrates CLI validation and adds checks for manifest, structure, skills quality, commands, agents, path safety, and version sync.
Capture output for analysis in Task 3.
Verification: Health check completed with error/warning counts.
Task 3: Analyze Findings Against Checklist
Goal: Deep analysis beyond the automated script.
Important: Read references/plugin-health-checklist.md for the full checklist.
The script catches structural issues. Manual analysis catches:
- Skill trigger overlaps
- Cross-component duplication
- Distribution readiness problems
- README documentation gaps
- Hook safety concerns
For each finding, record:
- Category (from checklist)
- Severity: CRITICAL / WARNING / INFO
- Component affected
- Specific issue
- Suggested fix
Verification: All 9 checklist categories evaluated.
Task 4: Present Refactoring Plan
Goal: Show user the full findings and planned fixes.
Present ALL findings with detail. Do NOT summarize:
- Health check script output (errors and warnings)
- Manual analysis findings by severity
- Planned fix for each issue
Format:
| # | Severity | Category | Component | Issue | Planned Fix |
|---|
Ask: "以上是插件健康檢查結果，要開始修正嗎？"
Verification: User has confirmed the refactoring plan.
Task 5: Execute Refactoring
Goal: Fix all confirmed issues.
Important: Read references/plugin-structure-rules.md for official rules and execution order.
Important: All edits in main conversation. Never delegate writes to subagents.
Verification: Each fix applied and individually verified.
Task 6: Verify Fixes
Goal: Re-run health check to confirm all issues resolved.
Process:
- Re-run the Step 2 fallback chain (
uv run → python3 → python) on the refactored plugin
- Verify zero CRITICAL errors
- Verify all WARNING items from Task 3 are resolved
- Check no new issues introduced
If issues remain: Return to Task 5 and fix.
Produce final report with changes made (component, change, rationale) and before/after health check metrics.
Verification: Health check passes with zero errors.
Task 7: Verify Version Bump Documentation in Plugin CLAUDE.md
Goal: Plugin root CLAUDE.md lists every file containing this plugin's version string.
Detection: Read <plugin-root>/CLAUDE.md. Check for a section (typically "Version Bump Locations") that enumerates:
- Each file path + field holding this plugin's version (plugin.json, marketplace entry, README headers)
- Cross-package or manual-only locations flagged explicitly
- Conventional Commits → version mapping
If absent or incomplete: Add/update using the format defined in creating-plugins Task 6.
Release automation is orthogonal: Whether or not release-please / semantic-release is configured, the plugin CLAUDE.md is still required. Scripts fail; CLAUDE.md is the fallback Claude reads every session.
Verification: <plugin-root>/CLAUDE.md documents every version-bearing file for this plugin.
Red Flags - STOP
- "Skip health check"
- "Structure looks fine"
- "Fix without showing"
- "Skip re-verification"
- "Simple plugin"
- "I know the official structure"
Common Rationalizations
| Thought | Reality |
|---|
| "Skip health check" | Scripts catch what eyes miss. Always run it. |
| "Structure looks fine" | Anti-patterns hide in config files. Check all 9 categories. |
| "Fix without showing" | User must confirm before structural changes. |
| "Skip re-verification" | Fixes can break other things. Re-run the script. |
| "Simple plugin" | Simple plugins still need valid manifests and naming. |
| "I know the official structure" | Official structure evolves. Verify against the checklist. |
References
