Agent-Skills.md

Agent Skills: Migrating Plugins

Sets up or migrates a Claude Code plugin, routing to creating-plugins or the validating + refactoring pipeline. Use when user says "setup plugin", "migrate plugin", "plugin from scratch", "check my plugin", "turn this into a plugin", "package this as plugin".

UncategorizedID: wayne930242/Reflexive-Claude-Code/migrating-plugins
165

Install this agent skill to your local

pnpm dlx add-skill https://github.com/wayne930242/Reflexive-Claude-Code/tree/HEAD/plugins/rcc/skills/migrating-plugins

Skill Files

Browse the full folder contents for migrating-plugins.

Download Skill

Loading file tree…

plugins/rcc/skills/migrating-plugins/SKILL.md

Skill Metadata

Name
migrating-plugins
Description
Sets up or migrates a Claude Code plugin, routing to creating-plugins or the validating + refactoring pipeline. Use when user says "setup plugin", "migrate plugin", "plugin from scratch", "check my plugin", "turn this into a plugin", "package this as plugin".

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

| Component | Project | Plugin | |-----------|---------|--------| | CLAUDE.md | ✓ | ✗ | | .claude/rules/ | ✓ | ✗ | | .claude/settings.json | ✓ | ✗ (plugin has settings.json at root) | | .claude-plugin/plugin.json | ✗ | ✓ (manifest) | | marketplace.json | ✗ | ✓ (if marketplace) | | skills/ | .claude/skills/ | plugin-root/skills/ | | agents/ | .claude/agents/ | plugin-root/agents/ | | hooks/ | .claude/settings.json | plugin-root/hooks/hooks.json | | .mcp.json | ✓ | ✓ | | .lsp.json | ✗ | ✓ | | bin/ | ✗ | ✓ |

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:

| Level | Criteria | Route | |-------|----------|-------| | None | No plugin, no scripts, user wants new | → creating-plugins | | Pre-plugin | Script project without .claude-plugin/ — has scripts, tools, or .claude/ configs that can become plugin components | → Task 3 (conversion proposal) → creating-plugins | | Minimal | Has .claude-plugin/plugin.json but missing skills/agents/hooks | → validating-plugins → refactoring-plugins | | Complete | Has manifest + skills + agents or hooks | → validating-plugins → refactoring-plugins |

For Pre-plugin, scan and categorize existing assets:

| Asset Type | Example | Becomes | |------------|---------|---------| | Scripts with reusable logic | scripts/deploy.sh, tools/lint.py | bin/ executables or skill-bundled scripts | | Markdown instructions | .claude/commands/*.md | skills/ or commands/ | | Agent definitions | .claude/agents/*.md | agents/ | | Hook scripts | .claude/hooks/* | hooks/ | | Skill directories | .claude/skills/*/SKILL.md | skills/ | | MCP server configs | .mcp.json | .mcp.json | | Validation/linting scripts | scripts/validate.py | hooks/ |

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

| Excuse | Reality | |--------|---------| | "I know which one" | Multiple plugins can exist. Always list and confirm. | | "Can't be a plugin" | Any project with reusable scripts or instructions can become a plugin. | | "Ignore existing scripts" | Existing scripts are validated, working code. Reuse them. | | "Has manifest = complete" | A 3-field plugin.json is minimal at best. Check all components. | | "Skip validation" | claude plugin validate catches structural issues you can't see by reading. | | "Use current directory" | Plugin root may be nested. Resolve from marketplace.json or plugin.json. |

Skill Chain Reference

| Step | Skill | Purpose | |------|-------|---------| | 0 | validating-plugins | Batch scan all files for frontmatter, links, orphans | | 1 | refactoring-plugins | Health-check and fix against official best practices | | alt-a | creating-plugins | Scaffold new plugin (from scratch or from conversion proposal) |