Migrating Plugins

Migrating Plugins

Overview

Migrating plugins IS identifying what to work with, then routing to the correct workflow.

A workspace may contain existing plugins, a script project that should become a plugin, or nothing. This skill discovers the state, asks the user what they want, resolves paths, then routes.

Core principle: Discover what exists. Ask the user. Then route.

Routing

Pattern: Tree Handoff: auto-invoke Next: creating-plugins | validating-plugins → refactoring-plugins Chain: plugin

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

1. Discover and select target
2. Assess state and classify
3. Propose conversion (if pre-plugin)
4. Route to appropriate skill chain

Announce: "Created 4 tasks. Starting execution..."

Plugin vs Project: Key Differences

Task 1: Discover and Select Target

Goal: Find existing plugins or identify a script project to convert.

Discovery strategy (try in order):

1. Check for marketplace.json — scan for **/.claude-plugin/marketplace.json. Read plugins array for names and source paths.

2. Check for standalone plugins — scan for **/.claude-plugin/plugin.json. Each parent of .claude-plugin/ is a plugin root.

3. Check for script project — if no plugins found, scan for signs of a convertible project:

   • Script files (*.sh, *.py, *.js, *.ts) in root or scripts/, src/, bin/
   • README.md describing a tool or utility
   • Package manifest (package.json, pyproject.toml, Cargo.toml)
   • Existing .claude/ directory with skills, commands, or agents

4. Check user-specified path — if the user provided a path, use it directly.

For each plugin found, record:

• Name (from plugin.json name field)
• Root path
• Version
• Source path (from marketplace.json if applicable)

If multiple plugins found:

• Present numbered list, ask which to work on

If exactly one plugin found:

• Confirm: "Found plugin '[name]' at [path]. Proceed?"

If no plugins but script project detected:

• Announce: "No plugin found, but this looks like a script project that could become a plugin."
• List what was found (scripts, README, package manifest, .claude/ configs)
• Ask: "Do you want to package this as a Claude Code plugin?"

If nothing found:

• Ask: "Do you want to create a new plugin from scratch?"

Set the target path for all subsequent tasks.

Verification: Target is selected, path is resolved, user has confirmed.

Task 2: Assess State and Classify

Goal: Determine the maturity level of the target.

Maturity classification:

For Pre-plugin, scan and categorize existing assets:

For each asset found, record:

• Source path
• Type (script / instruction / agent / hook / skill / config)
• Suggested plugin component
• Line count

Run claude plugin validate if .claude-plugin/ exists.

Detect version bump documentation (record for routing):

• Plugin root CLAUDE.md exists AND contains a version-bump section listing every version-bearing file (plugin.json, marketplace entries, README headers)
• Record as version_bump_doc: present | absent | partial (partial = CLAUDE.md exists but section missing or incomplete)

Verification: Clear maturity classification with asset inventory. Version bump doc state recorded.

Task 3: Propose Conversion (Pre-plugin Only)

Skip if: Maturity is None, Minimal, or Complete.

Goal: Present a conversion proposal for the script project.

Conversion proposal format:

## Plugin Conversion Proposal

Plugin name: [suggested-name]
Source: [project path]

| # | Source | Type | Plugin Component | Action |
|---|--------|------|-----------------|--------|
| 1 | scripts/deploy.sh | script | bin/deploy.sh | Copy to bin/, make executable |
| 2 | .claude/commands/review.md | instruction | skills/reviewing/SKILL.md | Convert to skill with frontmatter |
| 3 | .claude/agents/checker.md | agent | agents/checker.md | Copy, verify frontmatter |
| 4 | scripts/lint.py | validator | hooks/lint.py + hooks.json | Wrap as PostToolUse hook |
| 5 | README.md | docs | README.md | Adapt for plugin installation |

Version bump doc: [present | absent | partial]
- If absent/partial: `creating-plugins` Task 6 will add the required section to plugin CLAUDE.md during conversion

Present to user for confirmation.

If confirmed:

• Pass the conversion proposal as context to creating-plugins
• creating-plugins will use the proposal to pre-populate the plugin structure instead of starting from scratch

If rejected:

• Ask what to change, revise proposal, present again

Verification: User has confirmed or revised the conversion proposal.

Task 4: Route to Appropriate Skill Chain

Goal: Invoke the correct skill with the target path.

Important: Always pass the target path to downstream skills.

If None:

• Invoke creating-plugins (its Task 6 ensures plugin CLAUDE.md documents version bump locations)

If Pre-plugin (after Task 3 confirmation):

• Invoke creating-plugins with the conversion proposal as context (including recorded version_bump_doc state)
• The proposal tells creating-plugins which files to move/convert instead of scaffolding from scratch
• creating-plugins Task 6 will fill the plugin CLAUDE.md section based on the recorded state

If Minimal or Complete:

• Invoke validating-plugins with plugin root path
• After validation, invoke refactoring-plugins with report, plugin root path, and recorded version_bump_doc state
• refactoring-plugins Task 7 verifies / fills the plugin CLAUDE.md version-bump section

Verification: Correct skill invoked with target path, context, and version bump doc state.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "I know which plugin they mean"
• "There's only one plugin, skip asking"
• "This project can't be a plugin"
• "Just create a new plugin, ignore existing scripts"
• "The plugin.json exists so it's complete"
• "Skip validation, just refactor"
• "I'll just use the current directory"

All of these mean: You're about to guess instead of discover. Scan, ask, then route.

Common Rationalizations

Skill Chain Reference