port-plugin

Plugin Porter

Convert Agent Alchemy plugins (skills, agents, hooks, references, MCP configs) into formats compatible with other AI coding platforms using an extensible markdown-based adapter framework, live platform research, and interactive conversion workflows.

CRITICAL: Complete ALL 7 phases. The workflow is not complete until Phase 7: Summary is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

Critical Rules

AskUserQuestion is MANDATORY

IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

• Every wizard question -> AskUserQuestion
• Selection questions -> AskUserQuestion
• Confirmation questions -> AskUserQuestion
• Yes/no consent questions -> AskUserQuestion
• Clarifying questions -> AskUserQuestion

Text output should only be used for:

• Summarizing selections and findings
• Presenting information and status updates
• Explaining context or conversion details

If you need the user to make a choice or provide input, use AskUserQuestion.

NEVER do this (asking via text output):

Which plugin groups would you like to port?
1. core-tools
2. dev-tools
3. sdd-tools

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "Plugin Groups"
      question: "Which plugin groups would you like to port?"
      options:
        - label: "core-tools"
          description: "3 skills, 2 agents — Deep analysis, codebase analysis, language patterns"
        - label: "dev-tools"
          description: "6 skills, 4 agents — Feature dev, code review, docs, changelog"
        - label: "sdd-tools"
          description: "6 skills, 3 agents — Spec creation, task management, execution"
      multiSelect: true

Plan Mode Behavior

CRITICAL: This skill performs an interactive conversion workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:

• DO NOT create an implementation plan for how to build the porting feature
• DO NOT defer conversion to an "execution phase"
• DO proceed with the full wizard and conversion workflow immediately
• DO write converted files to the output directory as normal

Phase Overview

Execute these phases in order, completing ALL of them:

1. Settings & Arguments - Load configuration and parse arguments
2. Plugin Selection Wizard - Interactive selection of plugin groups and components
3. Dependency Validation - Build dependency graph and detect missing references
4. Platform Research - Spawn research agent to investigate target platform

4.5. Dry-Run Preview - Optional preview of expected output before conversion

1. Wave-Based Conversion - Convert components via parallel agent team with incompatibility resolution
2. Output & Reporting - Write converted files, migration guide, and gap report
3. Summary - Present results and next steps

Phase 1: Settings & Arguments

Goal: Load configuration, parse arguments, and determine the target platform.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

• --target <platform> — Target platform slug (default: opencode)
• --dry-run — Preview mode; show expected output without writing files

Set TARGET_PLATFORM from --target value (default: opencode). Set DRY_RUN from --dry-run flag (default: false).

Step 2: Load Settings

Check if .claude/agent-alchemy.local.md exists and read for any plugin-tools section with settings:

- **plugin-tools**:
  - **default-target**: opencode
  - **default-output-dir**: ported/
  - **auto-research**: true

If settings exist, apply them as defaults (CLI arguments override settings file values).

Step 3: Validate Adapter

Check that an adapter file exists for the target platform:

1. Use Glob to check ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
2. If the adapter file exists, read it and store as ADAPTER
3. If no adapter file exists:
4. Inform the user: "No adapter file found for '{TARGET_PLATFORM}'. The research agent will investigate the platform from scratch, and a new adapter file can be created from the findings."
5. Set ADAPTER = null
6. Continue — the research phase will gather platform information

Step 4: Load Marketplace Registry

Read the marketplace registry to enumerate available plugin groups:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Parse the plugins array. Each entry has:

• name — Full plugin name (e.g., agent-alchemy-core-tools)
• version — Current version
• description — Brief description
• source — Relative path to plugin directory (e.g., ./core-tools)

Build a list of available plugin groups, extracting the short group name from the source path (e.g., core-tools from ./core-tools).

Exclude plugin-tools from the selection list — the porter should not attempt to port itself.

Phase 2: Plugin Selection Wizard

Goal: Guide the user through selecting which plugin groups and individual components to port.

Step 1: Target Platform Confirmation

Inform the user of the target platform and configuration:

Target platform: {TARGET_PLATFORM}
Adapter: {adapter file path or "None — research agent will investigate"}
Dry-run: {DRY_RUN}

Step 2: Group-Level Selection

Present all available plugin groups for selection using AskUserQuestion with multiSelect: true.

For each plugin group, scan its directory to count components:

1. Use Glob to count skills: claude/{group}/skills/*/SKILL.md
2. Use Glob to count agents: claude/{group}/agents/*.md
3. Use Glob to check for hooks: claude/{group}/hooks/hooks.json
4. Use Glob to count reference dirs: claude/{group}/skills/*/references/
5. Use Glob to check for MCP config: claude/{group}/.mcp.json

Build the selection options:

AskUserQuestion:
  questions:
    - header: "Plugin Group Selection"
      question: "Which plugin groups would you like to port to {TARGET_PLATFORM}?"
      options:
        - label: "{group-name} (v{version})"
          description: "{skill_count} skills, {agent_count} agents{, hooks}{, MCP config} — {marketplace description}"
      multiSelect: true

Edge case — Empty plugin group: If a scanned group has zero skills, zero agents, no hooks, and no MCP config, skip it from the selection list and note: "Skipped {group}: no portable components found."

Store the selected groups as SELECTED_GROUPS.

If no groups are selected (user cancels or selects nothing), use AskUserQuestion to confirm:

AskUserQuestion:
  questions:
    - header: "No Selection"
      question: "No plugin groups were selected. Would you like to start over or cancel?"
      options:
        - label: "Start over"
          description: "Return to group selection"
        - label: "Cancel"
          description: "Exit the porter"
      multiSelect: false

If "Start over", repeat Step 2. If "Cancel", end the workflow gracefully.

Step 3: Component-Level Selection

For each selected group, scan and enumerate all individual components, then present for selection.

Component scanning per group:

1. Skills: For each claude/{group}/skills/*/SKILL.md:
2. Read the frontmatter to extract name and description
3. Check for references/ subdirectory and count reference files
4. Format: skill:{group}/{skill-name} with description

1. Agents: For each claude/{group}/agents/*.md:
2. Read the frontmatter to extract name, description, and model
3. Format: agent:{group}/{agent-name} with description and model tier

1. Hooks: If claude/{group}/hooks/hooks.json exists:
2. Read the file and count hook entries
3. Format: hooks:{group} with hook count and event types

1. MCP Config: If claude/{group}/.mcp.json exists:
2. Read the file and list configured servers
3. F