From plugin-creator
Executes refactoring tasks from /assessor: reads task files, resolves dependencies, delegates to specialist agents (SKILL_SPLIT, AGENT_OPTIMIZE, DOC_IMPROVE), orchestrates parallel execution and tracks completion.
npx claudepluginhub jamie-bitflight/claude_skills --plugin plugin-creatorThis skill uses the workspace's default tool permissions.
This command continues from `/plugin-creator:assessor`. After planning completes, use this to execute the refactoring tasks.
Starts or completes refactoring tasks from task files. Updates status, implements acceptance criteria based on issue types like SKILL_SPLIT, and runs verification steps.
Executes approved implementation plans using parallel developer agents. Initializes shared state, performs integration review, and runs verification (lint, tsc, format, build). Use post-planning.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
This command continues from /plugin-creator:assessor. After planning completes, use this to execute the refactoring tasks.
<refactor_input> $ARGUMENTS </refactor_input>
<plugin_target>$1</plugin_target>
If <plugin_target/> is:
.md path: Use directlypython3-development): GLOB for .claude/plan/tasks-refactor-{slug}.mdREAD the task file completely. Extract:
IMPORTANT: Each task specifies its assigned Agent field. Use this to route to the correct specialized agent during execution.
The task file links to its design spec (e.g., refactor-design-{slug}.md). READ it to understand the overall refactoring plan.
Identify:
❌ NOT STARTED with all dependencies ✅ COMPLETE or "None"TodoWrite(todos=[
{"content": "Task {ID}: {Name}", "status": "pending", "activeForm": "Implementing {Name}"},
... for each task ...
{"content": "Final: Verify refactoring complete", "status": "pending", "activeForm": "Verifying completion"}
])
Route each task to the appropriate specialized agent based on the Agent field in the task:
| Issue Type | Agent | When to Use |
|---|---|---|
| SKILL_SPLIT | plugin-creator:refactor-skill | Tasks splitting large skills into smaller focused ones |
| AGENT_OPTIMIZE | subagent-refactorer | Tasks improving agent prompts and descriptions |
| DOC_IMPROVE | contextual-ai-documentation-optimizer | Tasks improving skill/agent documentation quality |
| ORPHAN_RESOLVE | contextual-ai-documentation-optimizer | Tasks integrating orphaned reference files |
| STRUCTURE_FIX | contextual-ai-documentation-optimizer | Tasks fixing broken links or structural issues |
| Validation | plugin-assessor | Post-refactoring validation tasks |
| Documentation | plugin-docs-writer | README and documentation generation tasks |
For each ready task, READ the Agent field from the task and launch that agent:
Agent(
subagent_type="{task.agent}", # From task's **Agent** field
description="Task {ID}: {Name}",
prompt="/start-refactor-task {task_file_path} --task {task_id}"
)
Parallel execution: If multiple tasks can parallelize, launch them in a SINGLE message with multiple Task calls.
Example parallel launch:
# Launch skill split tasks in parallel (no shared files)
Agent(
subagent_type="plugin-creator:refactor-skill",
description="Task 1: Split python3 core skill",
prompt="/start-refactor-task .claude/plan/tasks-refactor-python3-development.md --task 1"
)
Agent(
subagent_type="subagent-refactorer",
description="Task 2: Optimize python-cli-architect agent",
prompt="/start-refactor-task .claude/plan/tasks-refactor-python3-development.md --task 2"
)
When a sub-agent completes:
✅ COMPLETE in task filecompletedWHILE tasks remain incomplete:
ready = tasks where status=❌ and dependencies satisfied
IF ready is empty AND incomplete tasks exist:
→ Deadlock. Report blocked tasks and their dependencies.
parallel_groups = group ready tasks by "Can Parallelize With"
FOR each group:
Launch all tasks in group (single message if multiple)
Wait for completion
Update status
After completing refactoring tasks, you MUST validate:
Validate against authoritative plugin.json schema from claude-plugins-reference-2026:
Required validation steps:
# Validate plugin structure
claude plugin validate {plugin-directory}
Common plugin.json issues after refactoring:
| Issue | Cause | Fix |
|---|---|---|
agents: Invalid input | Used "./agents/" directory string instead of array | Change to array of file paths: ["./agents/file1.md", "./agents/file2.md"] |
name: Required | Missing required name field | Add "name": "plugin-name" in kebab-case |
| Invalid path format | Absolute paths or missing ./ prefix | All paths must be relative and start with ./ |
| Referenced file doesn't exist | Path in plugin.json points to moved/deleted file | Update paths to match new file locations after refactoring |
SOURCE: Lines 25-92 of claude-plugins-reference-2026/SKILL.md
If plugin includes hooks, validate hook configuration:
Hook validation checklist:
${CLAUDE_PLUGIN_ROOT} variablechmod +x script.sh)Valid hook events:
SOURCE: Lines 186-227 of claude-plugins-reference-2026/SKILL.md
If plugin bundles MCP servers, validate MCP configuration:
MCP validation checklist:
.mcp.json or inline in plugin.json)${CLAUDE_PLUGIN_ROOT} for plugin-relative pathsargs arrays are properly formattedSOURCE: Lines 235-270 of claude-plugins-reference-2026/SKILL.md
If plugin provides LSP servers, validate LSP configuration:
LSP validation checklist:
.lsp.json or inline in plugin.json)extensionToLanguage mapping is defined for all supported file typescommand references binary in PATH or uses absolute path with ${CLAUDE_PLUGIN_ROOT}IMPORTANT: LSP servers require separate binary installation. Plugin only configures connection, doesn't bundle the server.
Example LSP validation error:
LSP server 'gopls' not found in $PATH
→ User must install separately: go install golang.org/x/tools/gopls@latest
SOURCE: Lines 271-338 of claude-plugins-reference-2026/SKILL.md
CRITICAL: Plugins are copied to cache directory during installation. Validate path resolution:
Path resolution warnings to check:
../ parent directory references (will break after caching)./ prefix${CLAUDE_PLUGIN_ROOT} used in all hook/MCP/LSP commandsCommon caching issues:
| Issue | Problem | Solution |
|---|---|---|
../shared-utils reference | Parent directory not copied to cache | Use symlink or restructure marketplace to include shared dir |
Hook script uses relative path without ./ | Ambiguous path resolution | Change to ./scripts/hook.sh or use ${CLAUDE_PLUGIN_ROOT} |
| MCP server references user home directory | Won't work for other users | Use plugin-relative paths or environment variables |
SOURCE: Lines 349-398 of claude-plugins-reference-2026/SKILL.md
Agents included in plugin-creator:
subagent-refactorer - Used for AGENT_OPTIMIZE tasks (✅ included)contextual-ai-documentation-optimizer - Used for DOC_IMPROVE and ORPHAN_RESOLVE tasks (✅ included)plugin-assessor - Used for validation tasks (✅ included)Known external agent dependencies:
plugin-docs-writer - Used for documentation generation (not in plugin-creator)Action if external agent missing:
~/.claude/agents/ or project .claude/agents/When all tasks show ✅ COMPLETE:
AUTOMATICALLY invoke the ensure-complete command to trigger verification:
Skill(skill="plugin-creator:ensure-complete", args="{task_file_path}")
This runs 4 phases:
After ensure-complete finishes, CHECK if follow-up tasks were created:
GLOB for: .claude/plan/tasks-refactor-{plugin-slug}-followup*.md
IF follow-up tasks exist:
================================================================================
FOLLOW-UP TASKS IDENTIFIED
================================================================================
The review found issues that need resolution:
- {list of follow-up task files}
Continuing recursive refactoring...
================================================================================
Skill(skill="plugin-creator:implement-refactor", args="{followup_task_file_path}")
IF no follow-up tasks:
================================================================================
PLUGIN REFACTORING COMPLETE
================================================================================
Plugin: {plugin_name}
Task File: {task_file_path}
COMPLETED TASKS:
✅ Task {ID}: {Name}
✅ Task {ID}: {Name}
...
VERIFICATION PASSED:
✅ Plugin Validation: Score improved from X to Y
✅ Code Review: No issues found
✅ Documentation: Synced with implementation
All quality gates passed. Plugin refactoring is complete.
================================================================================
This command implements a recursive refactoring loop:
┌─────────────────────────────────────────────────────────────────┐
│ IMPLEMENT-REFACTOR │
│ │
│ ┌──────────────┐ ┌───────────────────┐ ┌──────────────┐ │
│ │ Execute │───▶│ Complete │───▶│ Follow-up │ │
│ │ All Tasks │ │ Refactor │ │ Tasks? │ │
│ └──────────────┘ └───────────────────┘ └──────┬───────┘ │
│ │ │
│ ┌────────────────────────┴───┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────┐ ┌─────────┐ │
│ │ YES │ │ NO │ │
│ └───┬────┘ └────┬────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌────────────┐ │
│ │ Recurse: │ │ DONE │ │
│ │ implement- │ │ Plugin │ │
│ │ refactor on │ │ Refactored │ │
│ │ follow-up tasks │ └────────────┘ │
│ └────────┬────────┘ │
│ │ │
│ └───────────────────────────────────┘
└─────────────────────────────────────────────────────────────────┘
The cycle continues until the review finds no more issues.
If a sub-agent reports failure:
🔄 IN PROGRESSIf no tasks are ready but tasks remain:
If sub-agent reports design spec conflicts with actual skill structure:
You coordinate. Sub-agents implement.
/start-refactor-taskIf a sub-agent is blocked by concurrent edits from another agent, that's expected in parallel execution. Help them understand the changes and continue.