port-master

Port Master

Extract the platform-agnostic intent from Claude Code plugins, producing clean markdown files that any agent harness developer can read and adapt. The output preserves the what and why of each skill, agent, and hook while removing implementation details tied to Claude Code.

The goal is portability through clarity — a developer familiar with any agent framework should be able to read the output and integrate it into their system without needing to understand Claude Code's internals.

Three output modes are supported:

• Full mode (default): Produces skills, agents, and hooks — preserves the original component structure in generic format. Supports two output layouts:
• Per-group (default): Each plugin group gets its own subdirectory with separate manifest and integration guide.
• Unified (--unified): All groups merged into a single directory — one manifest, one integration guide, components organized by type. Cross-group dependencies become internal. Only meaningful when converting multiple groups.
• Flatten mode (--flatten): Produces skills only — agents are converted to skills, hooks are absorbed into a lifecycle-hooks skill. Use this for agent harnesses that only support skills and not agents or hooks.
• Nested mode (--nested): Agents become pure markdown instruction files nested within their parent skill's agents/ directory. Hooks are absorbed into a lifecycle-hooks skill. Use this for harnesses that support sub-agent delegation but use skills as the primary organizational unit.

Complete ALL 5 phases. After completing each phase, immediately proceed to the next without waiting for user prompts.

Critical Rules

AskUserQuestion is MANDATORY

Use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

• Selection questions → AskUserQuestion
• Confirmation questions → AskUserQuestion
• Clarifying questions → AskUserQuestion

Text output is only for status updates, summaries, and informational context.

AskUserQuestion Option Limits

Each question in AskUserQuestion supports 2-4 options maximum (plus a built-in "Other" for free-text input). Never create questions with more than 4 options — use presets, categories, or follow-up questions to stay within limits. When users need to pick from a large set, list all available items in the question text and let users specify via "Other".

Plan Mode Behavior

This skill performs an interactive conversion workflow. When invoked during plan mode:

• Proceed with the full wizard and conversion workflow immediately
• Write converted files to the output directory as normal
• Do NOT create an implementation plan or defer work to an "execution phase"

Phase Overview

1. Configuration Wizard & Component Selection — Parse arguments, upfront wizard, load registry, interactive selection
2. Dependency Analysis — Build dependency graph, classify dependencies, plan smart resolution
3. Conversion — Transform each component using rules from references/conversion-rules.md
4. Output Generation — Write files, manifest, and integration guide
5. Summary — Present results and next steps

Phase 1: Configuration Wizard & Component Selection

Goal: Gather all configuration (plugins, output directory, output mode) upfront, then select components.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

• Plugin group name(s) — positional arguments
• --all — Convert all plugin groups
• --output <dir> — Output directory (default: ./ported/)
• --flatten — Skills-only output mode (agents converted to skills, hooks absorbed)
• --nested — Nested output mode (agents nested as pure markdown within parent skills, hooks absorbed)
• --unified — Unified output layout (all groups merged into a single directory tree; full mode only)

If both --flatten and --nested are provided, report an error: these flags are mutually exclusive. Ask the user to choose one.

If --unified is provided together with --flatten or --nested, report an error: --unified only applies to full mode.

If --unified is provided with only one group (not --all), ignore it silently — unified and per-group produce identical output for a single group.

Step 2: Load Marketplace Registry

Read the plugin registry to enumerate available plugin groups:

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

Parse the plugins array. Each entry has name, version, description, and source (relative path like ./core-tools). Extract the short group name from the source path.

Exclude plugin-tools from the selection list — the converter should not attempt to convert itself.

For each group, scan its directory to count components:

• Skills: Glob claude/{group}/skills/*/SKILL.md
• Agents: Glob claude/{group}/agents/*.md
• Hooks: check for claude/{group}/hooks/hooks.json

Step 3: Configuration Wizard

Present configuration options via AskUserQuestion. Build the questions array dynamically — include only questions that still need user input (skip questions fully answered by arguments).

If ALL arguments were provided (valid plugin names or --all, plus --output and --flatten or --nested), skip this step entirely and proceed to Step 4.

Otherwise, build the questions array from the following, including only the ones needed. Combine applicable questions into a single AskUserQuestion call (max 4 questions per call).

Q1: Plugin Groups — include unless --all was specified or all positional args are valid group names.

List all available groups (with component counts) in the question text so users can reference them when choosing "Other". Use preset-based options to stay within the 4-option limit:

- header: "Plugin Groups"
  question: "Which plugin groups would you like to convert? Available: {group1} ({N} skills, {M} agents), {group2} (...), ..."
  options:
    - label: "All groups"
      description: "Convert all {count} available plugin groups"
    - label: "Core stack"
      description: "core-tools + dev-tools + claude-tools"
    - label: "SDD pipeline"
      description: "sdd-tools + tdd-tools + claude-tools"
  multiSelect: false

Build the preset options dynamically from the available groups — create 2-3 logical groupings based on the plugin descriptions. The user can always type specific group names via the built-in "Other" option.

If positional arguments named specific plugins but any name is invalid, note the invalid name in the question text: "'{invalid-name}' was not found."

Q2: Output Directory — include unless --output was provided:

- header: "Output"
  question: "Where should the converted files be written?"
  options:
    - label: "./ported/ (Recommended)"
      description: "Standard ported output location — timestamped subdirectory created automatically"
    - label: "Custom path"
      description: "Specify a different output directory"
  multiSelect: false

Q3: Output Mode — include unless --flatten or --nested was provided:

- header: "Output Mode"
  question: "What output format should be used?"
  options:
    - label: "Full (skills, agents, hooks)"
      description: "Preserves original component structure in generic format"
    - label: "Skills only (flatten)"
      description: "Converts agents to skills, absorbs hooks — for harnesses that only support skills"
    - label: "Nested (skills with embedded agents)"
      description: "Agents nested as pure markdown in parent skills, hooks absorbed — for harnesses using skills as primary unit"
  multiSelect: false

Q4: Output Layout — include only when ALL of these conditions are met:

• Output mode is "Full" (not flatten or nested) — determined by arguments or Q3 answer
• Multiple groups are selected or --all was specified — determined by arguments or Q1 answer
• --unified was NOT already provided as an argument