
agent-alchemy-plugin-tools
Agent Alchemy Plugin Tools — plugin lifecycle tools for AI agents
- version
- 0.2.6
- GitHub stars
- 45
Install
/plugin install agent-alchemy-plugin-tools@agent-alchemyRun it inside Claude Code after adding the marketplace with /plugin marketplace add sequenzia/agent-alchemy.
Contents
Discovered from sourceSkills 6
Bump Plugin Version
Automate version bumps across the Agent Alchemy ecosystem. Scans 5 version locations per plugin, detects drift, applies consistent updates, adds a CHANGELOG entry, and creates a conventional commit.
CRITICAL: Complete ALL 6 phases. The workflow is not complete until Phase 6: Commit 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.
- Plugin selection -> AskUserQuestion
- Bump level selection -> AskUserQuestion
- Drift resolution -> AskUserQuestion
- Confirmation prompts -> AskUserQuestion
Text output should only be used for:
- Displaying progress updates between phases
- Presenting inventory tables and drift reports
- Phase transition markers
If you need the user to make a choice or provide input, use AskUserQuestion.
NEVER do this (asking via text output):
Which plugins would you like to bump?
1. core-tools
2. dev-tools
ALWAYS do this (using AskUserQuestion tool):
AskUserQuestion:
questions:
- header: "Plugins"
question: "Which plugins would you like to bump?"
options:
- label: "core-tools (0.1.1)"
description: "Current version: 0.1.1"
- label: "dev-tools (0.1.1)"
description: "Current version: 0.1.1"
multiSelect: true
Plan Mode Behavior
CRITICAL: This skill performs an interactive version bump workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:
- DO NOT create an implementation plan for how to build the bumper
- DO NOT defer the version bump to an "execution phase"
- DO proceed with the full workflow immediately
- DO make file edits as normal
Phase Overview
Execute these phases in order, completing ALL of them:
- Discovery — Read marketplace.json, build plugin inventory with current versions
- Drift Check — Scan all 5 version locations for inconsistencies
- Selection — Choose plugins and bump level, compute new versions
- Bump — Edit all 5 version locations per plugin
- Changelog — Add entries under
## [Unreleased]in CHANGELOG.md - Commit — Stage modified files and create a conventional commit
Phase 1: Discovery
Goal: Read the marketplace registry and build a complete plugin inventory.
Step 1: Parse Arguments
Parse $ARGUMENTS for:
--plugin <group,...>— Comma-separated list of plugin groups to bump (e.g.,--plugin core-tools,dev-tools). Default: prompt for selection in Phase 3.--level patch|minor|major— Bump level. Default: prompt for selection in Phase 3.--dry-run— Show what would change without modifying files. Default:false.
Set variables:
PLUGIN_FILTERfrom--pluginvalue (default:null= prompt in Phase 3)BUMP_LEVELfrom--levelvalue (default:null= prompt in Phase 3)DRY_RUNfrom--dry-runflag (default:false)
Step 2: Load Marketplace Registry
Read the marketplace registry:
Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json
Build a plugin map from the plugins array:
{
group_name -> {
marketplace_name: "agent-alchemy-{group}",
version: "x.y.z",
source_dir: "{group}"
}
}
The group_name is derived from the source field by stripping the leading ./.
Step 3: Display Inventory
Display the current plugin inventory:
[Phase 1/6] Plugin Inventory
| Plugin | Marketplace Name | Current Version |
|--------|-----------------|-----------------|
| core-tools | agent-alchemy-core-tools | 0.1.1 |
| dev-tools | agent-alchemy-dev-tools | 0.1.1 |
| sdd-tools | agent-alchemy-sdd-tools | 0.1.2 |
| tdd-tools | agent-alchemy-tdd-tools | 0.1.0 |
| git-tools | agent-alchemy-git-tools | 0.1.0 |
| plugin-tools | agent-alchemy-plugin-tools | 0.1.0 |
Phase 2: Drift Check
Goal: Scan all 5 version locations and detect inconsistencies against marketplace.json (the source of truth).
Version Locations
For each plugin, versions appear in up to 5 locations:
| # | File | Description |
|---|---|---|
| 1 | claude/.claude-plugin/marketplace.json | Source of truth — JSON "version" field |
| 2 | CLAUDE.md (root) | Plugin Inventory table — | {group} | ... | {version} | |
| 3 | docs/index.md | Project Status table — | {Display Name} | {version} | {status} | |
| 4 | docs/plugins/index.md | At a Glance table — | [{Name}](...) | ... | {version} | |
| 5 | docs/plugins/{group}.md | Per-plugin doc file — format varies (see Per-Plugin Formats below) |
Per-Plugin Doc Formats (Location 5)
Each plugin doc uses a different version format. When scanning, look within the first 15 lines:
| Plugin | Format | Example |
|---|---|---|
| core-tools | Parenthetical in prose + vertical table | Core Tools (v0.1.1) provides... and | **Version** | 0.1.1 | |
| dev-tools | Bold metadata line | **Version:** 0.1.1 | **Skills:** ... |
| sdd-tools | Bold metadata with plugin name | **Plugin:** ... | **Version:** 0.1.2 | ... |
| tdd-tools | Backtick-wrapped parenthetical | (`v0.1.0`) in prose |
| git-tools | Bold metadata line | **Version:** 0.1.0 | **Skills:** ... |
| plugin-tools | Bold metadata with plugin name | **Plugin:** ... | **Version:** 0.1.0 | ... |
Step 1: Scan All Locations
For each plugin in the inventory:
-
Location 2 (CLAUDE.md): Read the Plugin Inventory table. Find the row matching the plugin group name. Extract the version from the last column.
-
Location 3 (docs/index.md): Read the Project Status table. Find the row matching the plugin's display name. Extract the version. Note: not all plugins may be listed here — skip silently if absent.
-
Location 4 (docs/plugins/index.md): Read the At a Glance table. Find the row matching the plugin name. Extract the version from the Version column.
-
Location 5 (docs/plugins/{group}.md): Read the first 15 lines. Search for the version string using the format described in Per-Plugin Formats above.
Compare each found version against the marketplace.json version (Location 1). Record any mismatches.
Step 2: Present Drift Report
[Phase 2/6] Version Drift Check
✓ No drift detected — all locations consistent.
Or if drift is found:
[Phase 2/6] Version Drift Check
| Plugin | Location | Expected | Found |
|--------|----------|----------|-------|
| core-tools | docs/plugins/core-tools.md | 0.1.1 | 0.1.0 |
| dev-tools | CLAUDE.md | 0.1.1 | 0.1.0 |
Step 3: Resolve Drift (if any)
If drift was detected, present resolution options via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Drift"
question: "Version drift detected in N locations. How should we proceed?"
options:
- label: "Fix drift first"
description: "Update drifted locations to match marketplace.json before bumping"
- label: "Ignore and bump"
description: "Proceed with version bump — drifted locations will be overwritten with new version"
- label: "Abort"
description: "Stop the workflow to investigate manually"
multiSelect: false
If Fix drift first: Use Edit to update each drifted location to match marketplace.json, then continue to Phase 3.
If Ignore and bump: Continue to Phase 3. The bump will overwrite with the new version anyway.
If Abort: Display the drift details and exit.
Phase 3: Selection
Goal: Determine which plugins to bump and the bump level. Compute new versions.
Step 1: Select Plugins
If PLUGIN_FILTER was provided via --plugin, use those plugins. Validate each against the inventory — warn and skip any that don't exist.
Otherwise, present a multi-select via AskUserQuestion listing all plugins with their current versions. The options should include each plugin as a selectable item.
Step 2: Select Bump Level
If BUMP_LEVEL was provided via --level, use it.
Otherwise, ask via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Bump Level"
question: "What type of version bump?"
options:
- label: "Patch (x.y.Z)"
description: "Bug fixes, minor updates — most common for skill changes"
- label: "Minor (x.Y.0)"
description: "New features, new skills or agents"
- label: "Major (X.0.0)"
description: "Breaking changes to skill interfaces or agent contracts"
multiSelect: false
Step 3: Compute New Versions
For each selected plugin, compute the new version by applying the bump level:
- patch: Increment the third segment (0.1.1 → 0.1.2)
- minor: Increment the second segment, reset third to 0 (0.1.1 → 0.2.0)
- major: Increment the first segment, reset second and third to 0 (0.1.1 → 1.0.0)
Step 4: Display Bump Plan
[Phase 3/6] Bump Plan
| Plugin | Current | New | Level |
|--------|---------|-----|-------|
| core-tools | 0.1.1 | 0.1.2 | patch |
| dev-tools | 0.1.1 | 0.1.2 | patch |
If DRY_RUN is true:
[Dry Run] No files will be modified. Showing what would change:
Files that would be edited:
- claude/.claude-plugin/marketplace.json (2 entries)
- CLAUDE.md (2 rows in Plugin Inventory)
- docs/index.md (2 rows in Project Status — if present)
- docs/plugins/index.md (2 rows in At a Glance)
- docs/plugins/core-tools.md (2 version occurrences)
- docs/plugins/dev-tools.md (1 version occurrence)
- CHANGELOG.md (1 new entry)
Dry run complete.
Then stop — do NOT proceed to Phase 4.
Phase 4: Bump
Goal: Edit all 5 version locations for each selected plugin.
CRITICAL: Track every file modified in a MODIFIED_FILES list for Phase 6 staging.
Location 1: marketplace.json
Read claude/.claude-plugin/marketplace.json. For each selected plugin, use Edit to replace the old version string with the new one. Target the specific "version": "old_version" line within that plugin's entry block.
Location 2: CLAUDE.md (Plugin Inventory Table)
Read the Plugin Inventory table in the root CLAUDE.md. For each selected plugin, find the row matching the group name and use Edit to replace the old version with the new version in that row. Use enough surrounding context to ensure a unique match.
Location 3: docs/index.md (Project Status Table)
Read the Project Status table in docs/index.md. For each selected plugin, find the row matching the plugin's display name. Use Edit to replace the old version with the new one.
Note: Not all plugins appear in this table. If a plugin is not found, skip silently — do not abort or warn.
Location 4: docs/plugins/index.md (At a Glance Table)
Read the At a Glance table in docs/plugins/index.md. For each selected plugin, find the row and use Edit to replace the old version with the new one.
Location 5: Per-Plugin Doc Files
For each selected plugin, read the first 15 lines of docs/plugins/{group}.md and update version occurrences using the format-specific patterns:
core-tools — Two occurrences:
- Parenthetical:
(v{old})→(v{new})in the prose paragraph - Vertical table:
| **Version** | {old} |→| **Version** | {new} |
dev-tools — One occurrence:
- Bold metadata:
**Version:** {old}→**Version:** {new}
sdd-tools — One occurrence:
- Bold metadata:
**Version:** {old}→**Version:** {new}
tdd-tools — One occurrence:
- Backtick parenthetical:
(`v{old}`)→(`v{new}`)
git-tools — One occurrence:
- Bold metadata:
**Version:** {old}→**Version:** {new}
plugin-tools — One occurrence:
- Bold metadata:
**Version:** {old}→**Version:** {new}
Strategy for Each Edit
- Read the file (or use already-read content)
- Search for the old version string in the expected location/format
- Use Edit with enough surrounding context for a unique match
- If the pattern is not found, warn and skip — do not abort the entire workflow
- Add the file path to
MODIFIED_FILES
Display Progress
After completing all edits:
[Phase 4/6] Version Bump Complete
Updated N files across N plugins:
- claude/.claude-plugin/marketplace.json ✓
- CLAUDE.md ✓
- docs/index.md ✓ (N of N plugins found)
- docs/plugins/index.md ✓
- docs/plugins/core-tools.md ✓ (2 occurrences)
- docs/plugins/dev-tools.md ✓ (1 occurrence)
If any locations were skipped:
Skipped:
- docs/index.md: plugin-tools not found in table (OK — not listed)
Phase 5: Changelog
Goal: Add version bump entries under ## [Unreleased] in CHANGELOG.md.
Step 1: Read CHANGELOG.md
Read CHANGELOG.md from the repository root. Find the ## [Unreleased] section.
Step 2: Build Entry
Group bumped plugins by version transition for concise entries. For example, if core-tools and dev-tools both went from 0.1.1 to 0.1.2:
### Changed
- Bump core-tools and dev-tools from 0.1.1 to 0.1.2
If plugins had different starting versions:
### Changed
- Bump core-tools and dev-tools from 0.1.1 to 0.1.2
- Bump sdd-tools from 0.1.2 to 0.1.3
Step 3: Insert Entry
Use Edit to insert the changelog entry immediately after the ## [Unreleased] line. If there is already content under [Unreleased], add the new entry after any existing entries (before the next ## [x.y.z] heading or end of section). If a ### Changed section already exists under [Unreleased], append to it rather than creating a duplicate.
Add CHANGELOG.md to MODIFIED_FILES.
Display Progress
[Phase 5/6] Changelog Updated
Added entry under [Unreleased]:
- Bump core-tools and dev-tools from 0.1.1 to 0.1.2
Phase 6: Commit
Goal: Stage all modified files and create a conventional commit.
Step 1: Stage Files
Stage each file in MODIFIED_FILES individually using git add:
git add claude/.claude-plugin/marketplace.json
git add CLAUDE.md
git add docs/index.md
git add docs/plugins/index.md
git add docs/plugins/core-tools.md
git add docs/plugins/dev-tools.md
git add CHANGELOG.md
CRITICAL: Do NOT use git add -A or git add .. Only stage files that were actually modified by this skill.
Step 2: Create Commit
Build the commit message:
Single plugin:
chore(marketplace): bump {group} to {new_version}
Multiple plugins, same new version:
chore(marketplace): bump {group1}, {group2} to {new_version}
Multiple plugins, different new versions:
chore(marketplace): bump {group1} to {v1}, {group2} to {v2}
Create the commit:
git commit -m "$(cat <<'EOF'
chore(marketplace): bump core-tools, dev-tools to 0.1.2
EOF
)"
Step 3: Verify and Report
Run git status to verify the commit succeeded.
[Phase 6/6] Committed
chore(marketplace): bump core-tools, dev-tools to 0.1.2
Staged files: N
Commit: {short_hash}
If the commit fails (e.g., pre-commit hook):
- Display the error output
- Do NOT use
--amendor--no-verify - Suggest the user fix the issue and run
/git-commitmanually
Error Handling
Missing Doc Files
If a docs/plugins/{group}.md file doesn't exist for a selected plugin, warn and skip:
Warning: docs/plugins/{group}.md not found — skipping Location 5 for {group}
Unmatched Version Patterns
If a version string can't be found at an expected location:
Warning: Could not find version {old} in {file} at expected location — skipping
Continue with other locations. Do not abort.
Plugin Not in Docs Table
If a plugin doesn't appear in docs/index.md or docs/plugins/index.md tables, skip silently. These tables may not list all plugins.
Git Commit Failure
If git commit fails:
- Report the full error output
- Do NOT use
--amend(would modify the previous commit) - Do NOT use
--no-verify(would skip hooks) - Suggest manual resolution
No Plugins Selected
If the user selects no plugins in Phase 3, display a message and exit:
No plugins selected. Exiting.
Invalid Bump Level
If --level has an unrecognized value, warn and prompt via AskUserQuestion.
Dependency Checker
Analyze the Agent Alchemy plugin ecosystem to detect dependency issues, broken paths, orphaned components, and documentation drift. Produces a health report with severity-ranked findings.
CRITICAL: Complete ALL 5 phases. The workflow is not complete until Phase 5: Report 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.
- Report presentation -> AskUserQuestion
- Action selection -> AskUserQuestion
- View mode selection -> AskUserQuestion
Text output should only be used for:
- Displaying progress updates between phases
- Presenting intermediate analysis summaries (inventory counts, graph stats)
- Phase transition markers
If you need the user to make a choice or provide input, use AskUserQuestion.
NEVER do this (asking via text output):
Would you like to view findings by severity or by plugin group?
1. By severity
2. By plugin group
ALWAYS do this (using AskUserQuestion tool):
AskUserQuestion:
questions:
- header: "View Mode"
question: "How would you like to view the findings?"
options:
- label: "By severity"
description: "Group findings from critical to low"
- label: "By plugin group"
description: "Filter findings to a specific plugin group"
multiSelect: false
Plan Mode Behavior
CRITICAL: This skill performs an interactive analysis workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:
- DO NOT create an implementation plan for how to build the analysis
- DO NOT defer analysis to an "execution phase"
- DO proceed with the full analysis workflow immediately
- DO write report files as normal if
--report-fileis specified
Phase Overview
Execute these phases in order, completing ALL of them:
- Load & Discover — Parse arguments, load settings, build component inventory
- Build Dependency Graph — Parse every component file to extract dependency edges
- Analyze — Run 7 detection passes over the dependency graph
- Cross-Reference Documentation — Compare graph against CLAUDE.md/README docs for drift
- Report — Present findings interactively; optionally export
Phase 1: Load & Discover
Goal: Parse arguments, load settings, build a complete component inventory of the plugin ecosystem.
Step 1: Parse Arguments
Parse $ARGUMENTS for:
--plugin <group>— Filter to one plugin group by short directory name (e.g.,core-tools). Default: analyze all groups.--verbose— Include healthy/passing entries in the report, not just issues. Default:false.--report-file <path>— Export the full report as a markdown file to the given path. Default: none (interactive only).
Set variables:
FILTER_GROUPfrom--pluginvalue (default:null= all groups)VERBOSE_MODEfrom--verboseflag (default:false)REPORT_FILEfrom--report-filevalue (default:null)
Step 2: Load Settings
Read settings from .claude/agent-alchemy.local.md if it exists. Look for the plugin-tools.dependency-checker section in the YAML frontmatter.
| Setting | Default | Description |
|---|---|---|
severity-threshold | low | Minimum severity to show: critical, high, medium, low |
check-docs-drift | true | Whether to run Phase 4 documentation cross-referencing |
line-count-tolerance | 10 | Percentage tolerance for line count drift in CLAUDE.md tables |
If the settings file doesn't exist or the section is missing, use defaults.
Step 3: Load Marketplace Registry
Read the marketplace registry:
Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json
Build a registry map: { plugin_name -> { version, source_dir, description } } for each entry in the plugins array. The source_dir is derived from the source field (strip leading ./).
Step 4: Discover Components
For each plugin group directory under claude/ (or only FILTER_GROUP if set), enumerate all components using Glob:
Skills:
Glob: claude/{group}/skills/*/SKILL.md
For each found skill, read its YAML frontmatter to extract:
name,description,user-invocable,disable-model-invocationallowed-toolslistskillslist (if present — for agent-like skill composition)
Agents:
Glob: claude/{group}/agents/*.md
For each found agent, read its YAML frontmatter to extract:
name,description,modeltoolslistskillslist (these are skill bindings that must resolve to real skills)
Shared references (plugin-level):
Glob: claude/{group}/references/**/*.md
Skill-local references:
Glob: claude/{group}/skills/*/references/**/*.md
Hooks:
Glob: claude/{group}/hooks/hooks.json
If found, read and parse the JSON to extract hook entries.
Hook scripts:
Glob: claude/{group}/hooks/*.sh
Step 5: Display Inventory Summary
Display a text summary of what was discovered:
[Phase 1/5] Plugin Ecosystem Inventory
| Group | Skills | Agents | Shared Refs | Skill Refs | Hooks | Scripts |
|-------|--------|--------|-------------|------------|-------|---------|
| core-tools | N | N | N | N | N | N |
| dev-tools | N | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... | ... |
| **Total** | **N** | **N** | **N** | **N** | **N** | **N** |
Phase 2: Build Dependency Graph
Goal: Parse every component file to extract all dependency edges, building a directed graph of the ecosystem.
Step 1: Define Edge Types
The graph has the following edge types:
| Edge Type | Source | Target | Pattern |
|---|---|---|---|
skill-loads-skill | Skill | Skill (same plugin) | ${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md (without /../) |
skill-loads-skill-cross | Skill | Skill (other plugin) | ${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md |
skill-loads-shared-ref | Skill | Shared reference | ${CLAUDE_PLUGIN_ROOT}/references/{path} |
skill-loads-local-ref | Skill | Skill-local reference | ${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{path} |
skill-loads-cross-ref | Skill | Cross-plugin reference | ${CLAUDE_PLUGIN_ROOT}/../{group}/(skills/{name}/)?references/{path} |
skill-spawns-agent | Skill | Agent | subagent_type references in skill body |
skill-reads-registry | Skill | Registry | ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/ patterns |
agent-binds-skill | Agent | Skill | skills: list in YAML frontmatter |
hook-runs-script | Hook config | Hook script | ${CLAUDE_PLUGIN_ROOT}/hooks/{script} in command strings |
Step 2: Extract Edges from Skills
For each SKILL.md file discovered in Phase 1, scan the full file content (not just frontmatter) using these regex patterns:
Cross-plugin skill loads:
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md
Creates edge: skill-loads-skill-cross from current skill to {group}:{skill_name}
Same-plugin skill loads:
\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/SKILL\.md
Match only if the path does NOT contain /../ before it. Creates edge: skill-loads-skill from current skill to {skill_name} within the same plugin.
Shared reference loads (same plugin):
\$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"'`)+]+\.md)
Creates edge: skill-loads-shared-ref
Skill-local reference loads:
\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"'`)+]+\.md)
Creates edge: skill-loads-local-ref
Cross-plugin reference loads:
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"'`)+]+\.md)
Creates edge: skill-loads-cross-ref
Agent spawning:
subagent_type[:\s]*["']?([^"'\s,}]+)
Creates edge: skill-spawns-agent from current skill to the resolved agent name.
Registry reads:
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.claude-plugin/
Creates edge: skill-reads-registry
Step 3: Extract Edges from Agents
For each agent .md file, parse its YAML frontmatter and extract the skills: list.
Each entry in the skills: list creates an agent-binds-skill edge. The skill name must be resolved to a skill within the same plugin group as the agent (since agent frontmatter skill bindings are group-local).
Step 4: Extract Edges from Hooks
For each hooks.json file, parse the JSON and scan all command strings for script references:
\$\{CLAUDE_PLUGIN_ROOT\}/hooks/([^\s"']+)
Creates edge: hook-runs-script from the hook config to the referenced script file.
Step 5: Display Graph Summary
[Phase 2/5] Dependency Graph Built
Nodes: N total (N skills, N agents, N shared refs, N skill refs, N hooks, N scripts)
Edges: N total
- skill-loads-skill: N (same-plugin: N, cross-plugin: N)
- skill-loads-ref: N (shared: N, local: N, cross-plugin: N)
- skill-spawns-agent: N
- skill-reads-registry: N
- agent-binds-skill: N
- hook-runs-script: N
Phase 3: Analyze (7 Detection Passes)
Goal: Run 7 detection passes over the dependency graph to find issues. Each pass produces findings with a severity level.
Filter findings by severity-threshold setting — only retain findings at or above the configured threshold.
Pass 1: Circular Dependencies (Critical)
Run DFS cycle detection on the skill-loads-skill and skill-loads-skill-cross edges (the skill-to-skill subgraph).
Algorithm:
- For each skill node, perform DFS tracking the visit stack
- If a node is encountered that is already in the current visit stack, a cycle is detected
- Record the full cycle path:
skill_A -> skill_B -> ... -> skill_A
Each cycle found is a Critical severity finding.
Pass 2: Missing Dependencies (High)
For every edge in the graph, verify that the target node exists on disk:
skill-loads-skill/skill-loads-skill-cross: Check the target SKILL.md file existsskill-loads-shared-ref/skill-loads-local-ref/skill-loads-cross-ref: Check the target .md file existsskill-spawns-agent: Resolve the agent name to a file. Agent names may be:- Bare names (e.g.,
"code-explorer") — look in the same plugin group'sagents/directory - Qualified names (e.g.,
"agent-alchemy-core-tools:code-explorer") — map marketplace name to source dir, then look in that group'sagents/
- Bare names (e.g.,
agent-binds-skill: Check the skill exists in the same plugin group'sskills/directoryhook-runs-script: Check the script file exists
Each missing target is a High severity finding. Include the source file, expected target path, and edge type.
Pass 3: Broken Cross-Plugin Paths (Medium)
Scan all SKILL.md and agent .md files for path anti-patterns:
Anti-pattern 1 — Marketplace name in path:
agent-alchemy-[a-z-]+/
Paths should use short directory names (e.g., core-tools), not marketplace names (e.g., agent-alchemy-core-tools).
Anti-pattern 2 — Hardcoded absolute paths:
/Users/|/home/|/tmp/.*claude/
Paths should use ${CLAUDE_PLUGIN_ROOT} variable, not absolute paths.
Anti-pattern 3 — Incorrect nesting depth:
\$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.\./
Triple ../ or deeper should not appear (maximum is ../../ for registry access).
Each finding is Medium severity.
Pass 4: Orphaned Components (Low)
Find components with zero inbound edges (nothing references them):
- Skills: Only flag non-user-invocable skills with zero inbound edges. User-invocable skills are entry points and are expected to have no inbound edges.
- Agents: Flag agents with zero
skill-spawns-agentinbound edges (no skill spawns them) AND zeroagent-binds-skilloutbound edges isn't sufficient — check that nothing spawns them. - Shared references: Flag
.mdfiles inreferences/directories with zeroskill-loads-shared-reforskill-loads-cross-refinbound edges. - Skill-local references: Flag
.mdfiles inskills/*/references/with zeroskill-loads-local-refinbound edges. - Hook scripts: Flag
.shfiles inhooks/with zerohook-runs-scriptinbound edges.
Each orphaned component is a Low severity finding. Note: files in references/adapters/ subdirectories may be dynamically loaded based on arguments and should be flagged with a caveat noting they may be loaded dynamically.
Pass 5: Agent-Skill Mismatches (High)
For each agent's skills: list in its frontmatter:
-
Unresolvable skill names: The skill name doesn't match any skill in the same plugin group. Flag as High severity with the agent name, unresolvable skill name, and a suggestion of possible matches (fuzzy).
-
Ambiguous cross-plugin bindings: If the skill name matches skills in multiple plugin groups but no qualifier is provided, flag as High severity.
Note: Agent skills: bindings in Claude Code are resolved within the same plugin group. A skill name in an agent's skills: list refers to a skill directory name under the agent's own plugin group's skills/ directory.
Pass 6: Marketplace Consistency (Medium)
Compare the marketplace registry against actual directories:
-
Missing registry entries: Directories under
claude/that look like plugin groups (containskills/oragents/subdirectories) but have no corresponding entry inmarketplace.json. Exclude.claude-plugin/itself. -
Stale registry entries: Entries in
marketplace.jsonwhosesourcepath doesn't resolve to an existing directory. -
Source path mismatches: Registry entry
sourcefield doesn't match the actual directory name.
Each finding is Medium severity.
Pass 7: Hook Integrity (Low)
For each hooks.json file:
-
Invalid matcher patterns: Check that
matchervalues reference valid Claude Code tool names. Known valid tools include:Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch,Task,AskUserQuestion,NotebookEdit,SendMessage,TodoWrite. Matchers using|for OR are valid. Flag unrecognized tool names. -
Missing scripts: Already covered by Pass 2 (missing dependencies), but if the script reference uses a non-standard path pattern (not
${CLAUDE_PLUGIN_ROOT}/hooks/), flag it. -
Timeout values: If
timeoutis set, verify it's a positive number. Flag zero or negative timeouts. -
Invalid hook types: Verify
typefield is a recognized value (command,prompt).
Each finding is Low severity.
Step: Display Analysis Summary
[Phase 3/5] Analysis Complete
| Pass | Check | Severity | Findings |
|------|-------|----------|----------|
| 1 | Circular dependencies | Critical | N |
| 2 | Missing dependencies | High | N |
| 3 | Broken cross-plugin paths | Medium | N |
| 4 | Orphaned components | Low | N |
| 5 | Agent-skill mismatches | High | N |
| 6 | Marketplace consistency | Medium | N |
| 7 | Hook integrity | Low | N |
| | **Total** | | **N** |
Phase 4: Cross-Reference Documentation
Goal: Compare the dependency graph against documentation files (CLAUDE.md, plugin README files) to detect drift. Skip this phase if the check-docs-drift setting is false.
If check-docs-drift is false, display:
[Phase 4/5] Documentation cross-referencing skipped (check-docs-drift: false)
Then proceed to Phase 5.
Check 1: CLAUDE.md Plugin Inventory Table
Read the root CLAUDE.md file and parse the Plugin Inventory table.
For each row in the table:
- Skill count: Compare the comma-separated skill names in the "Skills" column against the actual skills discovered in Phase 1. Flag missing or extra skills.
- Agent count: Compare the comma-separated agent names in the "Agents" column against actual agents. Flag missing or extra agents.
- Version: Compare the version in the table against the version in
marketplace.json. Flag mismatches.
Each drift finding is Medium severity with type docs-drift.
Check 2: CLAUDE.md Composition Chains
Read the Key Skill Composition Chains section in CLAUDE.md. For each documented chain:
- Verify the source skill exists
- Verify the target skill/agent exists
- Check that the edge exists in the dependency graph (the source actually loads/spawns the target)
Flag documented chains that don't match the actual graph as Medium severity docs-drift.
Do NOT flag undocumented chains — CLAUDE.md only documents "key" chains, not all of them.
Check 3: CLAUDE.md Critical Plugin Files Table
Read the Critical Plugin Files table. For each row:
- Verify the file exists at the listed path
- Get the actual line count using
Bash: wc -l - Compare against the documented line count. Apply the
line-count-tolerancesetting (default 10%). Flag if the actual count differs by more than the tolerance percentage.
Each finding is Low severity with type docs-drift.
Check 4: Plugin README Files
For each plugin group, read its README.md (if it exists):
- Parse the skills table and compare listed skills against actual skills in that group
- Parse the agents table and compare listed agents against actual agents in that group
Flag missing or extra entries as Medium severity with type docs-drift.
Display Documentation Summary
[Phase 4/5] Documentation Cross-Reference
| Source | Check | Findings |
|--------|-------|----------|
| CLAUDE.md | Plugin Inventory | N |
| CLAUDE.md | Composition Chains | N |
| CLAUDE.md | Critical Files | N |
| README files | Skill/Agent tables | N |
| **Total** | | **N** |
Phase 5: Report
Goal: Present findings interactively; optionally export as a markdown file.
Step 1: Compute Health Score
health_score = (components_without_issues / total_components) × 100
Where total_components is the count of all skills, agents, references, and scripts discovered in Phase 1. A component "has issues" if it appears in any finding from Phase 3 or Phase 4.
Determine health indicator:
- 90-100%: "Healthy"
- 70-89%: "Needs Attention"
- 50-69%: "Outdated"
- 0-49%: "Critical Issues"
Step 2: Auto-Export (if --report-file)
If REPORT_FILE is set, write the full report before presenting the interactive menu. The markdown report should include:
- Header with ecosystem name, date, health score
- Inventory summary table from Phase 1
- Dependency graph statistics from Phase 2
- Dependency graph diagram — Load
Read ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/technical-diagrams/SKILL.md, then generate a Mermaid flowchart showing plugin groups as subgraphs and key cross-plugin dependency edges. Limit to 15-20 nodes max. Highlight nodes involved in findings usingdanger(critical) orwarning(high) classDef styles. - All findings grouped by severity (critical → low), each with:
- Component involved
- Issue type and description
- Expected vs actual (where applicable)
- Suggested fix
- Documentation drift findings from Phase 4 (if run)
- Health score and recommendation
Write: {REPORT_FILE}
Display: Report exported to: {REPORT_FILE}
Step 3: Present Interactive Report
Present the summary via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Dependency Health Report"
question: |
## Plugin Ecosystem — {health_indicator}
**Health Score: {health_score}%** ({components_without_issues}/{total_components} components clean)
| Severity | Count |
|----------|-------|
| Critical | N |
| High | N |
| Medium | N |
| Low | N |
{total_findings} findings across {groups_with_issues} plugin groups.
How would you like to explore the results?
options:
- label: "View all findings"
description: "Findings grouped by severity, from critical to low"
- label: "View by plugin group"
description: "Select a plugin group to see its findings"
- label: "View dependency graph"
description: "Text-based graph showing all dependency edges"
- label: "Done"
description: "Exit the dependency checker"
multiSelect: false
Step 4: Handle User Selections
View all findings: Display all findings grouped by severity (critical first), each showing:
- Component: The file or component involved
- Issue: Description of the problem
- Expected: What was expected (if applicable)
- Actual: What was found (if applicable)
- Fix: Suggested remediation
After displaying, loop back to the interactive menu (Step 3).
View by plugin group: Present a follow-up AskUserQuestion with the plugin groups as options. After the user selects a group, display only findings involving components in that group. Then loop back to the interactive menu.
View dependency graph: Display a text-based representation of the dependency graph:
core-tools/
skills/
deep-analysis
-> spawns: code-explorer (core-tools), code-synthesizer (core-tools)
<- loaded by: codebase-analysis (core-tools), feature-dev (dev-tools), docs-manager (dev-tools), create-spec (sdd-tools)
codebase-analysis
-> loads: deep-analysis (core-tools)
-> loads ref: report-template.md, actionable-insights-template.md
agents/
code-explorer
-> binds: project-conventions, language-patterns
<- spawned by: deep-analysis
...
Also generate a Mermaid flowchart version showing plugin groups as subgraphs with color-coded finding severity (danger classDef for critical, warning for high, primary/secondary for clean nodes). Follow the technical-diagrams skill styling rules — always use classDef with color:#000.
After displaying, loop back to the interactive menu.
Done: Exit the workflow. Display a final one-line summary:
Dependency check complete. {total_findings} findings ({critical_count} critical, {high_count} high).
Error Handling
No Plugin Groups Found
If no plugin group directories are found under claude/ (or the filtered group doesn't exist):
- Display an error message listing what was searched
- If
--pluginwas used, suggest valid group names from the marketplace registry - Exit the workflow
Marketplace Registry Missing
If marketplace.json doesn't exist or can't be parsed:
- Log a warning:
Warning: marketplace.json not found or invalid. Skipping marketplace consistency checks (Pass 6). - Continue with all other passes — the registry is only needed for Pass 6 and documentation drift checks.
Malformed Component Files
If a SKILL.md or agent .md file can't have its YAML frontmatter parsed:
- Log a warning for that specific file
- Skip edge extraction for that file
- Add a Medium severity finding:
"Malformed frontmatter: {file_path}" - Continue processing other files
Large Ecosystem Performance
The analysis reads every component file. For performance:
- Read frontmatter-only when only frontmatter fields are needed (agents)
- Read full file content when body scanning is needed (skills — for
subagent_typeand path patterns) - Use Glob results from Phase 1 to avoid redundant file discovery
Finding Schema
Every finding produced by Phase 3 and Phase 4 follows this structure:
{
id: "{pass_number}.{index}",
severity: "critical" | "high" | "medium" | "low",
type: "circular-dep" | "missing-dep" | "broken-path" | "orphaned" |
"agent-skill-mismatch" | "marketplace-inconsistency" |
"hook-integrity" | "docs-drift",
component: "{group}/{component_type}/{name}",
message: "Human-readable description of the issue",
expected: "What was expected (optional)",
actual: "What was found (optional)",
fix: "Suggested remediation"
}
Dependency Patterns Reference
These are the regex patterns used in Phase 2 for edge extraction. They are provided here as a quick reference — the authoritative patterns are in Phase 2 above.
| Dependency Type | Regex Pattern |
|---|---|
| Cross-plugin skill load | \$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md |
| Same-plugin skill load | \$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/SKILL\.md (without preceding /../) |
| Shared reference load | \$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"' )]+\.md) |
| Skill-local reference load | \$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"' )]+\.md) |
| Cross-plugin reference | \$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"' )]+\.md) |
| Agent spawning | subagent_type[:\s]*["']?([^"'\s,}]+) |
| Registry read | \$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.claude-plugin/ |
| Hook script | \$\{CLAUDE_PLUGIN_ROOT\}/hooks/([^\s"']+) |
| Agent skill binding | YAML skills: list in agent frontmatter |
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 alifecycle-hooksskill. 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'sagents/directory. Hooks are absorbed into alifecycle-hooksskill. 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
- Configuration Wizard & Component Selection — Parse arguments, upfront wizard, load registry, interactive selection
- Dependency Analysis — Build dependency graph, classify dependencies, plan smart resolution
- Conversion — Transform each component using rules from
references/conversion-rules.md - Output Generation — Write files, manifest, and integration guide
- 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
--allwas specified — determined by arguments or Q1 answer --unifiedwas NOT already provided as an argument
- header: "Output Layout"
question: "How should the output be organized?"
options:
- label: "Per-group (Recommended)"
description: "Each group in its own subdirectory with separate manifest and integration guide"
- label: "Unified"
description: "All groups merged into one directory — single manifest, single integration guide, components organized by type"
multiSelect: false
Store results as:
SELECTED_GROUPS— plugin groups to convert (parse from preset or "Other" text)OUTPUT_DIR— base output directory (before timestamp)FLATTEN_MODE— boolean, true if "Skills only" selected or--flattenprovidedNESTED_MODE— boolean, true if "Nested" selected or--nestedprovidedUNIFIED_LAYOUT— boolean, true if "Unified" selected or--unifiedprovided. Always false in flatten/nested mode or when only one group is selected
Step 4: Component-Level Selection
For each selected group, enumerate components by reading frontmatter from each file to extract name and description. Count skills, agents, and hooks.
Present a simplified selection per group using preset options (stays within 4-option limit). List all component names in the question text so users know what's available:
AskUserQuestion:
questions:
- header: "{group-name}"
question: "Select components from {group-name} ({total} total — Skills: {skill_names}; Agents: {agent_names}; Hooks: {yes/no}):"
options:
- label: "All components (Recommended)"
description: "Convert all {total} components"
- label: "Skills only"
description: "Convert {skill_count} skills, skip agents and hooks"
- label: "Custom selection"
description: "Specify which components to include via text"
multiSelect: false
If multiple groups are selected, you can ask about all groups in a single AskUserQuestion call (one question per group, max 4 questions per call). For more than 4 groups, use multiple sequential calls.
If the user selects "Custom selection" or types specific names via "Other", parse their response to build the component list.
In flatten mode, add context to the question text:
- Note that agents will be converted to skills and hooks will be absorbed into a lifecycle-hooks skill
In nested mode, add context to the question text:
- Note that agents will be nested as pure markdown instruction files within their parent skill's
agents/directory - Note that hooks will be absorbed into a lifecycle-hooks skill (same as flatten)
Build SELECTED_COMPONENTS — a flat list:
[{ type: "skill"|"agent"|"hooks", group: "{group}", name: "{name}", path: "{file path}" }]
Step 5: Confirm Selection
Present a summary table showing selected components, output mode, and output directory. Confirm with the user:
AskUserQuestion:
questions:
- header: "Confirm"
question: "Proceed with converting {count} components? Output: {output_mode}{layout_suffix}, Directory: {OUTPUT_DIR}"
options:
- label: "Proceed"
description: "Continue to dependency analysis"
- label: "Modify"
description: "Change configuration"
- label: "Cancel"
description: "Exit"
multiSelect: false
Where {output_mode} is "Full", "Flatten (skills only)", or "Nested (skills with embedded agents)". {layout_suffix} is (unified layout) when UNIFIED_LAYOUT is true, empty string otherwise.
Phase 2: Dependency Analysis & Resolution Planning
Goal: Map all dependencies between selected components and plan how to resolve them in the generic output.
Step 1: Parse Dependencies
For each component in SELECTED_COMPONENTS, read its source file and scan for dependency patterns.
Six dependency patterns to detect:
| Pattern | Example | Type |
|---|---|---|
| Same-plugin skill load | Read ${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md | skill-to-skill |
| Cross-plugin load | ${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md | cross-plugin |
| Reference file include | ${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{file} | reference |
| Agent spawn | subagent_type: "{name}" or subagent_type: "{plugin}:{name}" | agent-ref |
| Agent skill preload | skills: array in agent frontmatter | agent-to-skill |
| Agent-to-agent reference | Agent body mentions another agent by name in spawning context | agent-to-agent |
Also detect external dependencies (MCP servers, shell scripts) for informational tracking.
Step 2: Classify Dependencies
For each dependency found, classify it:
| Classification | Meaning | Action |
|---|---|---|
| Internal | Target is in SELECTED_COMPONENTS | Will be converted; reference by name |
| External-available | Target exists on disk but wasn't selected | Reference by name in manifest |
| External-missing | Target doesn't exist locally | Note as unresolved in manifest |
| Reference file | Points to a references/*.md file | Smart resolution (see Step 3) |
Unified layout adjustment: When UNIFIED_LAYOUT is active, dependencies that would be classified as External-available between selected groups are reclassified as Internal. A component from group A that depends on a component from group B (both selected) is internal in unified mode because both exist in the same output directory. Only dependencies pointing to groups NOT in SELECTED_GROUPS remain external.
Step 3: Smart Resolution Planning
For each reference file dependency, determine how to handle it based on line count, consumer count, and consumer type.
- Count lines in the referenced file using
Bash: wc -l < {path} - Determine the primary owner — the skill whose source directory originally contained the reference file (from the source path
skills/{owner}/references/{file}). If the primary owner was not selected for conversion, assign ownership to the first selected consumer - Identify all consumers — which skills and agents use this reference
Decision logic for skill-consumed references:
- Under 250 lines AND single consumer → mark for inline (content will be embedded directly in the consuming skill's SKILL.md)
- 250+ lines AND single consumer → mark as separate in the consuming skill's
references/directory - Multiple skill consumers → mark as separate in the primary owner skill's
references/directory; other consumers reference via relative path../{owner-skill}/references/{file}
Decision logic for agent-consumed references (full mode):
- Under 250 lines → mark for inline into the agent's body
- 250+ lines → mark as promote_to_skill — the reference becomes a new skill at
skills/{ref-name}/SKILL.mdwith its content as the body. The agent's converted text will reference it as a dependency. If the name collides with an existing skill, prefix with the agent name:{agent-name}-{ref-name}
Decision logic for agent-consumed references (flatten mode):
When FLATTEN_MODE is active, agents are converted to skills. Use skill-consumed rules instead of promote_to_skill:
- Under 250 lines AND single consumer → mark for inline into the agent-as-skill's body
- 250+ lines AND single consumer → mark as separate in the agent-as-skill's
references/directory - Multiple consumers → mark as separate in the primary owner skill's
references/directory
This avoids creating promoted skills when the agent itself is already becoming a skill — the reference can live directly in the agent-as-skill's own references/ directory.
Decision logic for agent-consumed references (nested mode):
When NESTED_MODE is active, agents are nested within their parent skill's directory. Use skill-consumed rules (same as flatten), but the "owning skill" for a nested agent's references is the parent skill from AGENT_PARENT_MAP:
- Under 250 lines AND single consumer → mark for inline into the nested agent's markdown body
- 250+ lines AND single consumer → mark as separate in the parent skill's
references/directory - Multiple consumers → mark as separate in the primary owner skill's
references/directory
This keeps all reference files at the skill directory level — nested agents don't have their own references/ subdirectory.
Mixed consumers (skill + agent): Skill-consumed rules take precedence. The agent references the owning skill's directory.
Unified layout adjustment: When UNIFIED_LAYOUT is active, cross-group reference resolution follows the same rules as same-group resolution. All skills are siblings under a single skills/ directory, so cross-skill paths use the standard ../{owner-skill}/references/{file} convention regardless of which group the skills originated from.
Store decisions as RESOLUTION_PLAN:
[{ ref_path, line_count, decision: "inline"|"separate"|"promote_to_skill", owner_skill: "{skill-name}", used_by: [component names] }]
Step 3b: Agent-to-Parent Mapping (Nested Mode Only)
Skip this step unless NESTED_MODE is active.
For each agent in SELECTED_COMPONENTS, determine which skill "owns" it — the parent skill under which the agent will be nested.
Detection patterns (ordered by priority):
subagent_typereferences — Scan all selected skills forsubagent_typepatterns matching the agent name (e.g.,subagent_type: "code-explorer"orsubagent_type: "core-tools:code-explorer"). Highest confidence.- Prose spawning references — Scan skill bodies and their reference files for the agent name appearing in spawning contexts (e.g., "launch a wave-lead", "spawn the code-explorer agent"). Lower confidence but catches agents referenced without
subagent_type. - Agent-to-agent chains — Scan other agents' bodies for references to this agent. If agent A spawns agent B, and agent A's parent is skill S, then agent B also nests under skill S.
Priority resolution when multiple skills reference the same agent:
- Same-group skill with
subagent_typetakes priority - Same-group skill with prose reference is second
- Agent-spawner's parent skill is third (for agent-to-agent chains)
- If still tied, the skill with the most references to the agent wins
Agent-spawns-agent chains: When an agent spawns another agent (e.g., wave-lead spawns context-manager), both nest under the same grandparent skill. The agents/ directory is flat — no nesting within nested agents.
Orphan agents: If no selected skill references an agent, mark it as orphan. Orphan agents will be promoted to standalone skills during Phase 3.
Store the mapping as AGENT_PARENT_MAP:
{ agent_name: parent_skill_name | "orphan" }
Step 4: Present Dependency Summary
Show the user:
- Total dependencies found
- How many will be inlined vs. kept as separate files
- Which skill directories will contain
references/subdirectories and what they own - Any references promoted from agent references to standalone skills
- Any external/missing dependencies that won't be included
- In nested mode, also show:
- Agent-to-parent mappings discovered (which agent nests under which skill)
- Any orphan agents that will be promoted to standalone skills
- Any agents referenced by multiple skills (which skill gets the nesting, which get cross-references)
- In unified layout, also show:
- Cross-group dependencies reclassified as internal (count and list)
- Any name collisions detected across groups (components with the same type and name from different groups)
- Ask for confirmation to proceed
Phase 3: Conversion
Goal: Transform each component into a clean, platform-agnostic format.
Before starting conversion, read the detailed transformation rules:
Read ${CLAUDE_PLUGIN_ROOT}/skills/port-master/references/conversion-rules.md
Process components in dependency order (leaf nodes first) so that when a component references another, the referenced component has already been converted.
Skill Conversion
For each skill:
- Read source — Read the SKILL.md file, split into YAML frontmatter and markdown body
- Transform frontmatter — Apply the Skill Frontmatter Rules from conversion-rules.md: keep
nameanddescription, remove platform-specific fields, adddependencieslist - Transform body — Apply all Body Transformation Rules from conversion-rules.md in order:
- Resolve
${CLAUDE_PLUGIN_ROOT}references (inline small content or addSee: {name}pointers) - Rewrite tool-specific language to generic descriptions
- Decompose orchestration patterns (teams, tasks, waves) into sequential/parallel prose
- Remove prompt engineering directives aimed at Claude specifically
- Generalize settings and configuration references (rule 3f)
- Apply
.claude/→.agents/path replacement (rule 3g)
- Resolve
- Append Integration Notes — Add a
## Integration Notessection describing what capabilities the target harness needs to support this skill - Store result for output in Phase 4
Agent Conversion (Full Mode)
Skip this section if FLATTEN_MODE or NESTED_MODE is active — use "Agent-to-Skill Conversion" or "Agent-to-Nested Conversion" below instead.
For each agent:
- Read source — Read the agent
.mdfile - Transform frontmatter — Keep
nameanddescription. Addrole(inferred from description: explorer, reviewer, architect, executor, etc.). Adddependenciesfor any preloaded skills - Transform body — Same rules as skills (including 3g path replacement), plus:
- Resolve
skills:preloads into prose ("This agent draws on knowledge from {skill-name}") - Remove tool-restriction prose ("You only have access to Read, Glob, Grep")
- Resolve
- Append Integration Notes
- Store result
Hook Conversion (Full Mode)
Skip this section if FLATTEN_MODE or NESTED_MODE is active — use "Hook-to-Skill Conversion" below instead.
For each hooks component:
- Read source — Read
hooks.jsonand parse JSON - Convert to YAML — Map Claude Code event names to generic lifecycle events using the Hook Event Mapping table from conversion-rules.md
- Process hook entries:
- Command hooks → Copy referenced scripts, resolve
${CLAUDE_PLUGIN_ROOT}paths to relative paths within the output directory. Apply rule 3g (.claude/→.agents/) to script content. Add a comment explaining what the script does (read the script to understand its purpose) - Prompt hooks → Preserve the prompt text as-is (already platform-agnostic). Apply rule 3g to any
.claude/paths in the prompt text
- Command hooks → Copy referenced scripts, resolve
- Add descriptions — For each hook entry, add a
descriptionfield explaining when and why this hook fires - Store result
Agent-to-Nested Conversion (Nested Mode)
Skip this section unless NESTED_MODE is active.
For each agent with a parent in AGENT_PARENT_MAP:
- Read source — Read the agent
.mdfile, split into YAML frontmatter and markdown body - Strip frontmatter — Remove YAML frontmatter entirely (no
---delimiters in output) - Structure as pure markdown — Apply the Agent-to-Nested Conversion Rules from Section 9 of conversion-rules.md:
# {Agent Name}title (from frontmattername)- One-line summary (from frontmatter
description) ## Role— Rewrite identity framing to role description. Keep the role-based voice (e.g., "Responsible for exploring codebases...") since this is still a sub-agent — do NOT use task instruction framing like flatten mode## Inputs— Document expected parameters the agent receives when spawned## Process— Preserve numbered workflow steps and phase structure from the body## Output Format— Document structured output format if applicable; omit if not## Guidelines— Consolidate behavioral rules and constraints; omit if none
- Transform body — Apply all standard Body Transformation Rules (3a-3g from conversion-rules.md) to the content within each section
- Convert
skills:preloads — Add "This agent draws on knowledge from:" in the Role section, listing each preloaded skill with a brief description - Remove tool-restriction prose — Same as full/flatten mode
- Store result for output at
skills/{parent-skill}/agents/{agent-name}.md
For each orphan agent (marked as orphan in AGENT_PARENT_MAP):
- Apply the Agent-to-Skill conversion rules (same as flatten mode, Section 7 of conversion-rules.md)
- Store as
skills/{agent-name}/SKILL.md - Append to Integration Notes: "Origin: Promoted from orphan agent
{name}— no parent skill in this package spawns this agent directly"
Parent Skill Augmentation (Nested Mode)
Skip this section unless NESTED_MODE is active.
After converting all nested agents, augment each parent skill's converted SKILL.md:
-
Add a
## Nested Agentssection listing all agents nested under this skill:## Nested Agents The `agents/` directory contains instructions for specialized sub-agents. Read them when spawning the relevant sub-agent. - `agents/{agent-name}.md` — {one-line description from the agent's original description} -
Rewrite spawn instructions in the parent skill's body to reference nested files:
- Before: "Spawn N agents via Agent tool with subagent_type: '{name}'"
- After: "Delegate to N independent {role} agents (see
agents/{name}.mdfor instructions)"
-
Add cross-references for agents nested under a different skill:
- "This step uses the {agent-name} agent from the {parent-skill} skill (see
../{parent-skill}/agents/{agent-name}.md)"
- "This step uses the {agent-name} agent from the {parent-skill} skill (see
-
Add sub-agent capability requirements to the parent skill's Integration Notes:
**Sub-agent capabilities:** - **{agent-name}**: Requires {capability list from the agent's original tools field}
Agent-to-Skill Conversion (Flatten Mode)
Only applies when FLATTEN_MODE is active. Each agent is converted to a skill.
For each agent:
- Read source — Read the agent
.mdfile, split into YAML frontmatter and markdown body - Build skill frontmatter:
name: Keep the agent namedescription: Keep the agent description. Append " (converted from agent)"dependencies: Merge the agent'sskills:preloads with any detected skill references in the body
- Transform body — Apply all standard Body Transformation Rules (3a-3g from conversion-rules.md), then apply the Agent-to-Skill Reframing Rules from Section 7 of conversion-rules.md:
- Rewrite agent identity framing ("You are a {role} that...") to task instructions ("When invoked, perform the following {role} tasks:")
- Remove tool-restriction prose ("You only have access to...")
- Convert
skills:preloads into "Prerequisites" section - Convert the agent's
toolslist into a capabilities paragraph in Integration Notes
- Append Integration Notes — Use the standard template plus:
- "Origin: Converted from agent
{name}— originally invoked as a sub-agent, not directly by the user" - If the agent had a specific
model(e.g., Opus, Sonnet), note: "Complexity hint: Originally ran on a {model-tier} model — may benefit from a more capable model for reasoning-heavy steps" - Include the Tool Capability Summary from Section 7 of conversion-rules.md
- "Origin: Converted from agent
- Store result as a skill entry (output to
skills/{name}/SKILL.md, notagents/)
Hook-to-Skill Conversion (Flatten and Nested Modes)
Only applies when FLATTEN_MODE or NESTED_MODE is active. ALL hooks from a group are merged into a single lifecycle-hooks skill.
If the group has no hooks, skip this section.
- Read source — Read
hooks.jsonand parse JSON - Check for name collision — If a skill named
lifecycle-hooksalready exists inSELECTED_COMPONENTSfor this group, use{group}-lifecycle-hooksas the name instead - Build skill frontmatter — Apply the structure from Section 8 of conversion-rules.md:
name:lifecycle-hooks(or{group}-lifecycle-hooksif collision)description: "Behavioral rules and lifecycle event handlers for the {group-name} package. (converted from hooks)"dependencies: []
- Build skill body — For each hook entry:
- Map the Claude Code event name to its generic name using Section 4 (Hook Event Mapping)
- Create a
## On {generic-event-name}subsection - For prompt hooks: include the prompt text verbatim as the rule body
- For command hooks: read the referenced script, summarize its behavior in prose, store the script in
skills/lifecycle-hooks/references/{script-name}.sh(with rule 3g applied to script content) - Group multiple hooks on the same event under one heading with matcher sub-sections
- Append Integration Notes — Use the template from Section 8 of conversion-rules.md
- Store result as a skill entry
Reference File Handling
For reference files marked as "separate" in the RESOLUTION_PLAN:
- Read the source file
- Clean any
${CLAUDE_PLUGIN_ROOT}paths in the content - Remove Claude Code-specific tool references if present
- Apply rule 3g (
.claude/→.agents/path replacement) to the content - Store for copying to the owning skill's
references/directory (i.e.,skills/{owner_skill}/references/{file})
For reference files marked as "promote_to_skill" (full mode only):
- Read the source file
- Apply the same body transformation rules (3a-3g from conversion-rules.md) to the content
- Wrap the content as a new skill with minimal frontmatter (
nameanddescriptioninferred from the reference content and heading) - Store as a new skill entry at
skills/{ref-name}/SKILL.md - Update the consuming agent's
dependencieslist to include the new skill name
For reference files marked as "inline" — their content was already embedded during skill/agent conversion.
Phase 4: Output Generation
Goal: Write all converted files, the manifest, and the integration guide.
Step 1: Create Timestamped Output Directory
The output directory (OUTPUT_DIR) was determined in Phase 1's Configuration Wizard.
Generate a timestamp in YYYYMMDD-HHMMSS format (e.g., 20260304-143052) using the current date and time.
Create the timestamped output directory structure:
{OUTPUT_DIR}/{YYYYMMDD-HHMMSS}/
└── {group-name}/
└── ...
Each selected group gets its own subdirectory under the timestamp. Store the full timestamped path as TIMESTAMPED_OUTPUT.
When UNIFIED_LAYOUT is active, skip group subdirectories — all components go directly under the timestamp:
{OUTPUT_DIR}/{YYYYMMDD-HHMMSS}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
├── skills/
├── agents/
└── hooks/
Step 2: Write Component Files
Create the output directory structure and write all converted files.
Full mode output structure:
{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
├── skills/
│ └── {name}/
│ ├── SKILL.md
│ └── references/ (only if this skill owns reference files)
│ └── {file}.md
├── agents/
│ └── {name}.md
└── hooks/
├── hooks.yaml
└── scripts/
└── {script-name}.sh
Full mode — unified layout output structure (when UNIFIED_LAYOUT is active):
{TIMESTAMPED_OUTPUT}/
├── manifest.yaml (single combined manifest)
├── INTEGRATION-GUIDE.md (single combined guide)
├── skills/
│ └── {name}/ (all skills from all groups, flat)
│ ├── SKILL.md
│ └── references/
│ └── {file}.md
├── agents/
│ └── {name}.md (all agents from all groups, flat)
└── hooks/
├── hooks.yaml (merged hooks from all groups)
└── scripts/
└── {script-name}.sh
Name collision handling: When merging components from different groups, names may collide (e.g., two groups both have a researcher agent). Detect collisions before writing:
- Build a map of
{component-type}:{name}across all groups - For any collision, prefix the component name with its origin group:
{group}-{name}(e.g.,sdd-researcherandplugin-researcher) - Update all internal references (dependency lists, spawn instructions, cross-references) to use the prefixed name
- Record the original name in the manifest's
original_namefield for traceability
Hooks merging: When multiple groups have hooks, merge all hook entries into a single hooks.yaml. Add an origin_group field to each entry. If script names collide across groups, prefix with group name: {group}-{script-name}.sh.
Flatten mode output structure (skills only — no agents/ or hooks/ directories):
{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
└── skills/
└── {name}/
├── SKILL.md
└── references/ (only if this skill owns reference files)
└── {file}.md
In flatten mode, this includes:
- Original skills (converted as normal)
- Agent-converted skills (from Agent-to-Skill conversion)
- The
lifecycle-hooksskill (from Hook-to-Skill conversion, if hooks existed in the source)
Nested mode output structure (skills with embedded agents — no top-level agents/ or hooks/):
{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
└── skills/
└── {name}/
├── SKILL.md
├── agents/ (only if this skill owns nested agents)
│ └── {agent-name}.md (pure markdown, no YAML frontmatter)
└── references/ (only if this skill owns reference files)
└── {file}.md
In nested mode, this includes:
- Original skills (converted as normal, augmented with
## Nested Agentssection if they own agents) - Nested agent instruction files within their parent skill's
agents/directory - Orphan agents promoted to standalone skills (from Agent-to-Skill conversion)
- The
lifecycle-hooksskill (from Hook-to-Skill conversion, if hooks existed in the source)
Each skill gets its own directory with SKILL.md inside. Reference files are co-located in the owning skill's references/ subdirectory — only create the references/ subdirectory when at least one separate reference file exists. There is no root-level references/ directory.
Write each converted component to its appropriate location.
Step 3: Generate manifest.yaml
The manifest provides a machine-readable inventory of the package:
name: {group-name}
description: {from marketplace registry}
mode: "full" # or "flatten" or "nested"
source:
platform: "Claude Code"
plugin: "{marketplace-name}"
version: "{version}"
converted: "{YYYY-MM-DD}"
components:
skills:
- name: {name}
file: skills/{name}/SKILL.md
description: {description}
origin: skill # "skill", "agent", or "hooks"
references: # only if this skill owns reference files
- name: {ref-name}
file: skills/{name}/references/{ref-name}.md
used_by: [{component names}]
agents: # omit this section in flatten mode
- name: {name}
file: agents/{name}.md
description: {description}
role: {role}
hooks: # omit this section in flatten mode
- event: {generic-event-name}
file: hooks/hooks.yaml
description: {what the hook does}
dependencies:
internal:
- from: {component}
to: {component}
relationship: "{what it loads/uses}"
external:
- from: {component}
to: {external name}
source_plugin: "{plugin group}"
relationship: "{what it needs}"
note: "Not included — convert separately if needed"
The origin field indicates whether each skill was originally a skill, an agent (converted to skill in flatten mode), or hooks (absorbed into lifecycle-hooks skill). In full mode, all skills have origin: skill.
Full mode — unified layout manifest (when UNIFIED_LAYOUT is active):
name: unified-export
description: "Combined export of {group1}, {group2}, ... plugin groups"
mode: "full"
layout: "unified"
source:
platform: "Claude Code"
groups:
- name: {group1}
plugin: "{marketplace-name-1}"
version: "{version-1}"
- name: {group2}
plugin: "{marketplace-name-2}"
version: "{version-2}"
converted: "{YYYY-MM-DD}"
components:
skills:
- name: {name}
file: skills/{name}/SKILL.md
description: {description}
origin: skill
origin_group: {group-name}
original_name: {original-name} # only present if renamed due to collision
references:
- name: {ref-name}
file: skills/{name}/references/{ref-name}.md
used_by: [{component names}]
agents:
- name: {name}
file: agents/{name}.md
description: {description}
role: {role}
origin_group: {group-name}
original_name: {original-name} # only present if renamed due to collision
hooks:
- event: {generic-event-name}
file: hooks/hooks.yaml
description: {what the hook does}
origin_group: {group-name}
dependencies:
internal: # includes cross-group deps that were external in per-group mode
- from: {component}
to: {component}
relationship: "{what it loads/uses}"
external: # only deps pointing to groups NOT in SELECTED_GROUPS
- from: {component}
to: {external name}
source_plugin: "{plugin group}"
relationship: "{what it needs}"
note: "Not included — convert separately if needed"
Key differences from per-group manifest: name is unified-export, layout: "unified" field added, source.groups is an array, every component has origin_group, and cross-group dependencies appear as internal.
In flatten mode, omit the agents and hooks sections entirely — all components appear under skills.
In nested mode, use mode: "nested" and represent agents within their parent skill entries:
mode: "nested"
components:
skills:
- name: {skill-name}
file: skills/{skill-name}/SKILL.md
description: {description}
origin: skill
nested_agents: # only if this skill has nested agents
- name: {agent-name}
file: skills/{skill-name}/agents/{agent-name}.md
description: {description}
origin: agent
role: {role}
references: # only if this skill owns reference files
- name: {ref-name}
file: skills/{skill-name}/references/{ref-name}.md
used_by: [{component names}]
- name: {orphan-agent-name} # orphan agents appear as top-level skills
file: skills/{orphan-agent-name}/SKILL.md
description: {description}
origin: agent
In nested mode, omit top-level agents and hooks sections. Agents appear as nested_agents within their parent skill. Orphan agents appear as top-level skill entries with origin: agent.
Step 4: Generate INTEGRATION-GUIDE.md
The guide helps harness developers understand and integrate the converted components.
Full mode:
# Integration Guide: {group-name}
## Overview
{What this package provides — summarize the plugin group's purpose}
## Component Inventory
| Component | Type | Description |
|-----------|------|-------------|
{table of all components}
## Capability Requirements
{What features the target harness needs — organized by category:}
- **File operations**: Which components need to read/write/search files
- **Shell execution**: Which components run shell commands
- **User interaction**: Which components prompt for user input
- **Sub-agent delegation**: Which components spawn child agents
- **Web access**: Which components fetch external content (if any)
## Per-Component Notes
{For each component, compile the Integration Notes section from the converted file}
## Dependency Map
{If more than 5 internal dependencies, include a text-based dependency diagram}
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Configure agent spawning for components that delegate to sub-agents
- [ ] Set up lifecycle hooks if your harness supports them
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining
Full mode — unified layout adjustments to the integration guide:
- Title:
# Integration Guide: Unified Export - Add an "Overview" paragraph explaining this package combines components from N groups, with a brief description of each group
- Add a "Source Groups" table:
## Source Groups
| Group | Original Plugin | Version | Skills | Agents | Hooks |
|-------|----------------|---------|--------|--------|-------|
{table of all source groups with component counts}
- The "Component Inventory" table adds an "Origin Group" column
- Add a "Name Collisions" section (omit entirely if no collisions occurred):
## Name Collisions
| Current Name | Original Name | Origin Group | Reason |
|-------------|---------------|-------------|--------|
{collision table}
- "Per-Component Notes" grouped by origin group with
### From {group}subheadings - "Dependency Map" is a single unified graph — cross-group dependencies appear as internal
- Update the "Adaptation Checklist":
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Configure agent spawning for components that delegate to sub-agents
- [ ] Set up lifecycle hooks if your harness supports them (hooks merged from {N} groups)
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] If components were renamed due to collisions, update any external references
- [ ] Test each component individually before combining
Flatten mode adjustments to the integration guide:
- The "Component Inventory" table uses "skill" for all types, with an "Origin" column showing the original type (skill, agent, hooks)
- The "Capability Requirements" section notes that agent and hook capabilities have been folded into skills
- Add a "Flatten Mode Notes" section after "Per-Component Notes":
## Flatten Mode Notes
This package was converted in flatten mode — all components are skills.
### Agent-Converted Skills
{List skills that were originally agents, with their original role context}
### Lifecycle Hooks Skill
{If lifecycle-hooks skill exists: describe the behavioral rules it contains and their original event triggers}
### Capability Notes
{Any tool-scope restrictions from original agents that consumers should be aware of}
- Update the "Adaptation Checklist" for flatten mode:
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Review agent-converted skills for role-appropriate context injection
- [ ] Implement lifecycle-hooks rules as middleware, event handlers, or manual checks
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining
Nested mode adjustments to the integration guide:
- The "Component Inventory" table includes columns: Component, Type, Origin, Parent Skill, Description. Nested agents have their parent skill listed; top-level skills and orphans have "—".
- The "Capability Requirements" section notes that agent capabilities are documented within their parent skill's Integration Notes under "Sub-agent capabilities"
- Add a "Nested Mode Notes" section after "Per-Component Notes":
## Nested Mode Notes
This package was converted in nested mode — agents are embedded within their parent skills as pure markdown instruction files.
### Nesting Map
| Agent | Parent Skill | Role | Purpose |
|-------|-------------|------|---------|
{table of agent-to-parent mappings from AGENT_PARENT_MAP}
### Reading Nested Agents
Each parent skill's SKILL.md contains a "Nested Agents" section listing its sub-agents with one-line descriptions. The agent files in `agents/` are pure markdown instructions — read them when spawning the corresponding sub-agent. They have no YAML frontmatter.
### Orphan Agents
{If any orphan agents were promoted to standalone skills, list them here with explanation. Otherwise: "No orphan agents — all agents are nested under a parent skill."}
### Cross-Skill Agent References
{If any skills reference agents nested under a different skill, list the cross-references here.}
### Lifecycle Hooks Skill
{Same as flatten mode — describe the behavioral rules it contains and their original event triggers, if hooks existed in the source}
- Update the "Adaptation Checklist" for nested mode:
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] For skills with nested agents, configure sub-agent spawning to read instructions from the agents/ directory
- [ ] Review orphan agents (promoted to standalone skills) for role-appropriate context
- [ ] Check cross-skill agent references and ensure relative paths work in your harness
- [ ] Implement lifecycle-hooks rules as middleware, event handlers, or manual checks
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining
Step 5: Write All Files
Write all files to the output directory using the Write tool. Track every file written for the summary.
Phase 5: Summary
Goal: Present conversion results and suggest next steps.
Results Table
## Conversion Complete
**Output mode:** {Full | Flatten (skills only) | Nested (skills with embedded agents)}
**Output directory:** {TIMESTAMPED_OUTPUT}
| Component | Type | Origin | Lines (source → output) | Notes |
|-----------|------|--------|------------------------|-------|
{for each component}
**Files written:** {count}
**Skill directories created:** {count}
**References inlined:** {count} ({total lines})
**References co-located with skills:** {count}
**References promoted to skills:** {count} (from agent references, full mode only)
**External dependencies:** {count} (not included)
In unified layout, add these additional stats:
**Output layout:** Unified
**Groups merged:** {count} ({group names})
**Cross-group deps internalized:** {count}
**Name collisions resolved:** {count} (renamed with group prefix)
In flatten mode, add these additional stats:
**Agents converted to skills:** {count}
**Hooks absorbed into lifecycle-hooks:** {count} ({hook_count} events)
In nested mode, add these additional stats:
**Agents nested within skills:** {count} (across {parent_count} parent skills)
**Orphan agents promoted to skills:** {count}
**Hooks absorbed into lifecycle-hooks:** {count} ({hook_count} events)
The "Origin" column shows "skill", "agent", or "hooks" — in full mode this always matches "Type", but in flatten mode it shows the original component type before conversion.
Next Steps
Suggest:
- Review the INTEGRATION-GUIDE.md for capability requirements
- Start with the simplest skill to validate integration with the target harness
- If external dependencies exist, note which plugin groups they come from
- For components that used team orchestration (now decomposed to sequential/parallel steps), test the simplified workflow to ensure it meets needs
- In flatten mode: review agent-converted skills to verify the reframing preserved the original intent
- In nested mode: verify agent-to-parent mappings — ensure each agent is nested under the skill that logically spawns it. Review cross-skill references for accuracy
- In unified layout: check renamed components (if any collisions occurred) and verify the unified dependency map captures all cross-group relationships
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:
- Settings & Arguments - Load configuration and parse arguments
- Plugin Selection Wizard - Interactive selection of plugin groups and components
- Dependency Validation - Build dependency graph and detect missing references
- Platform Research - Spawn research agent to investigate target platform 4.5. Dry-Run Preview - Optional preview of expected output before conversion
- Wave-Based Conversion - Convert components via parallel agent team with incompatibility resolution
- Output & Reporting - Write converted files, migration guide, and gap report
- 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:
- Use
Globto check${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md - If the adapter file exists, read it and store as
ADAPTER - If no adapter file exists:
- 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."
- Set
ADAPTER = null - 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 versiondescription— Brief descriptionsource— 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:
- Use
Globto count skills:claude/{group}/skills/*/SKILL.md - Use
Globto count agents:claude/{group}/agents/*.md - Use
Globto check for hooks:claude/{group}/hooks/hooks.json - Use
Globto count reference dirs:claude/{group}/skills/*/references/ - Use
Globto 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:
-
Skills: For each
claude/{group}/skills/*/SKILL.md:- Read the frontmatter to extract
nameanddescription - Check for
references/subdirectory and count reference files - Format:
skill:{group}/{skill-name}with description
- Read the frontmatter to extract
-
Agents: For each
claude/{group}/agents/*.md:- Read the frontmatter to extract
name,description, andmodel - Format:
agent:{group}/{agent-name}with description and model tier
- Read the frontmatter to extract
-
Hooks: If
claude/{group}/hooks/hooks.jsonexists:- Read the file and count hook entries
- Format:
hooks:{group}with hook count and event types
-
MCP Config: If
claude/{group}/.mcp.jsonexists:- Read the file and list configured servers
- Format:
mcp:{group}with server names
Present components for each group using AskUserQuestion:
AskUserQuestion:
questions:
- header: "{group-name} Components"
question: "Select components to port from {group-name}:"
options:
- label: "All components"
description: "Port everything in {group-name} ({total_count} components)"
- label: "skill: {skill-name}"
description: "{skill description} ({ref_count} references)"
- label: "agent: {agent-name}"
description: "{agent description} (model: {model})"
- label: "hooks: {group}"
description: "{hook_count} hooks ({event types})"
- label: "mcp: {group}"
description: "MCP config ({server names})"
multiSelect: true
Edge case — "All components" selected: If the user selects "All components", include every component from that group in the selection. Do not present further sub-selection.
Build the final component list as SELECTED_COMPONENTS, a flat list of component identifiers with their types:
[
{ type: "skill", group: "core-tools", name: "deep-analysis", path: "claude/core-tools/skills/deep-analysis/SKILL.md" },
{ type: "agent", group: "core-tools", name: "code-explorer", path: "claude/core-tools/agents/code-explorer.md" },
{ type: "hooks", group: "core-tools", name: "hooks", path: "claude/core-tools/hooks/hooks.json" },
...
]
Step 4: Selection Summary
Present a summary of the selection to the user:
## Selection Summary
**Target platform:** {TARGET_PLATFORM}
**Plugin groups:** {count} selected
**Total components:** {count}
| Group | Skills | Agents | Hooks | MCP | References |
|-------|--------|--------|-------|-----|------------|
| {group} | {n} | {n} | {yes/no} | {yes/no} | {n} files |
Components:
- {component list with types}
Use AskUserQuestion to confirm:
AskUserQuestion:
questions:
- header: "Confirm Selection"
question: "Proceed with this selection?"
options:
- label: "Proceed"
description: "Continue to dependency validation"
- label: "Modify selection"
description: "Go back and change component selection"
- label: "Cancel"
description: "Exit the porter"
multiSelect: false
If "Modify selection", return to Step 2. If "Cancel", end the workflow gracefully.
Phase 3: Dependency Validation
Goal: Build a full dependency graph from selected components, detect all five dependency types, flag missing references and external dependencies, and produce a dependency-sorted conversion order for Phase 5.
This phase consumes SELECTED_COMPONENTS and SELECTED_GROUPS from Phase 2 and produces DEPENDENCY_GRAPH (including CONVERSION_ORDER) for Phase 5.
Step 1: Parse Dependencies
For each component in SELECTED_COMPONENTS, read its source file and extract all dependency references. Initialize a flat dependency list:
DEPENDENCIES = [] // each entry: { source, target_type, target_ref, dep_type, raw_pattern, transitive }
Process each component type using the sub-steps below. Apply these error handling rules during scanning:
Error: Unreadable file. If a component file cannot be read (permission error, file missing, I/O error), log a warning and continue scanning the remaining components:
WARNING: Could not read {component.path} -- skipping dependency scan for this component.
Error: Malformed YAML frontmatter. If a component's YAML frontmatter cannot be parsed (invalid YAML between --- delimiters), log a parsing error and fall back to body-only scanning for that component:
WARNING: Malformed YAML frontmatter in {component.path} -- scanning body text only for dependencies.
1a: Skill Dependencies
For each skill component (type: "skill"), read its SKILL.md and scan for all five dependency types:
Dependency Type 1 -- Skill-to-skill references:
Scan the skill body for patterns that load another skill from the same plugin group:
Read ${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/SKILL.md
For each match, extract {skill-name} and record:
{ source: this_component, target_type: "skill", target_ref: "{this_group}/{skill-name}", dep_type: "skill-to-skill", raw_pattern: "{matched line}", transitive: false }
Dependency Type 2 -- Cross-plugin references:
Scan the body for patterns that reference a different plugin group:
${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/skills/{skill-name}/SKILL.md
${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/agents/{agent-name}.md
${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/
For each match, extract {source-dir-name} and the component name, and record:
{ source: this_component, target_type: "skill" or "agent", target_ref: "{source-dir-name}/{name}", dep_type: "cross-plugin", raw_pattern: "{matched line}", transitive: false }
Dependency Type 3 -- Reference file includes:
Scan the body for patterns that load reference files:
Read ${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/references/{filename}
${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/references/{filename}
For each match, determine if the reference belongs to this skill or another skill:
- References to this skill's own
references/directory are internal by definition and do not create a dependency edge - References to another skill's
references/directory create a dependency:
{ source: this_component, target_type: "reference", target_ref: "{group}/{skill-name}/references/{filename}", dep_type: "reference-include", raw_pattern: "{matched line}", transitive: false }
Dependency Type 4 -- Agent/subagent references:
Scan the body for Task tool invocations that spawn agents:
subagent_type: "{agent-name}"
For each match, record:
{ source: this_component, target_type: "agent", target_ref: "{group}/{agent-name}", dep_type: "skill-to-skill", raw_pattern: "{matched line}", transitive: false }
External dependencies (non-component):
Scan for system-level dependencies that cannot be ported as components:
- MCP server tool references: patterns like
mcp__{server}__{tool}or themcp__prefix in the body orallowed-toolslist - Bash script invocations: references to specific script files (paths ending in
.sh,.py,.js)
For each external dependency found:
{ source: this_component, target_type: "external", target_ref: "{description}", dep_type: "external", raw_pattern: "{matched line}", transitive: false }
1b: Agent Dependencies
For each agent component (type: "agent"), read its .md file:
Dependency Type 5 -- Agent-to-skill references:
Parse the YAML frontmatter and extract the skills: field (array of skill identifiers). For each skill listed:
{ source: this_component, target_type: "skill", target_ref: "{resolved skill reference}", dep_type: "agent-to-skill", raw_pattern: "skills: [{skill}]", transitive: false }
Also scan the agent's markdown body for Read ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT}/../ patterns, applying the same Type 1, Type 2, and Type 3 scans from Step 1a.
Tool dependencies (informational only):
Parse the tools: field from frontmatter. These are Claude Code platform tools classified as System dependencies. They do not create dependency edges but are tracked for the gap report.
1c: Hook Dependencies
For each hooks component (type: "hooks"), read the hooks.json file and parse the JSON:
Dependency Type 4 -- Hook-to-script references:
For each hook entry, extract the command field and scan for:
- Script file paths: any path in the command string (e.g.,
${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-approve.sh) - Direct script references: paths ending in
.sh,.py,.js, or other executable extensions
For each script reference:
{ source: this_component, target_type: "script", target_ref: "{script path}", dep_type: "hook-to-script", raw_pattern: "{command value}", transitive: false }
Tool matcher patterns in hooks reference Claude Code tool names -- classify these as System dependencies for informational tracking only.
1d: MCP Config Dependencies
For each MCP config component (type: "mcp"), read the .mcp.json file:
Each configured MCP server is an external dependency requiring manual porting on the target platform. Record each server:
{ source: this_component, target_type: "external", target_ref: "MCP server: {server_name} ({command})", dep_type: "external", raw_pattern: "{server config snippet}", transitive: false }
Step 2: Build Dependency Graph
Construct a directed dependency graph from the parsed dependencies.
2a: Create Graph Nodes and Edges
Nodes: All components in SELECTED_COMPONENTS, each identified by {type}:{group}/{name}.
Edges: For each entry in DEPENDENCIES where dep_type is NOT "external" and NOT a system dependency, create a directed edge from the source node to the node matching target_ref.
2b: Classify Each Dependency
For each dependency in DEPENDENCIES, determine its classification by checking target_ref against SELECTED_COMPONENTS and SELECTED_GROUPS:
| Classification | Condition |
|---|---|
| Internal | Target component exists in SELECTED_COMPONENTS |
| External-selected | Target component's group is in SELECTED_GROUPS but the specific component was not individually selected |
| External-missing | Target component's group is NOT in SELECTED_GROUPS and not available in the marketplace |
| System | Target is a Claude Code platform feature (built-in tool, MCP protocol feature) |
| External | Target is a non-component dependency (MCP server process, bash script, external service) |
2c: Resolve Deeply Nested References (Recursive)
Dependencies can form chains: Skill A loads Skill B, which loads Skill C, which loads Skill D. To ensure the full transitive dependency tree is captured:
- Start with the directly parsed dependencies from Step 1 (all have
transitive: false) - Build a set
SCANNED_COMPONENTScontaining all components already processed in Step 1 - For each dependency classified as
External-missingorExternal-selected: a. Determine the file path of the target component on disk (using the component scanning conventions:claude/{group}/skills/{name}/SKILL.mdfor skills,claude/{group}/agents/{name}.mdfor agents) b. If the file exists and the component is NOT inSCANNED_COMPONENTS:- Read the file and scan it using the same rules from Step 1a/1b/1c/1d
- Mark all newly discovered dependencies with
transitive: true - Add newly found dependencies to
DEPENDENCIES - Add the component to
SCANNED_COMPONENTSc. If the file does not exist, skip it (it will be reported as unresolvable in Step 4)
- Repeat step 3 for any newly discovered
External-missingorExternal-selecteddependencies - Recursion depth limit: Cap at depth 10 to prevent runaway expansion. If depth 10 is reached, log:
WARNING: Dependency chain depth limit (10) reached starting from {root component}. Some transitive dependencies may not be fully resolved.
2d: Detect Circular Dependencies
Run a cycle detection pass on the dependency graph using depth-first search:
- For each node in the graph, perform a depth-first traversal
- Maintain a traversal stack (current path from root)
- If a node is encountered that is already on the current stack, a cycle exists
- Record each unique cycle (avoid duplicates for cycles detected from different starting nodes):
CIRCULAR_REFS = [ { cycle: ["{component_id_1}", "{component_id_2}", ..., "{component_id_1}"], warning: "Circular dependency detected" } ] - Circular references are warnings that do not block conversion. They will be handled during Phase 5 via topological sort with cycle-breaking.
Step 3: Self-Contained Check
Before alerting the user, determine whether the selection has any unresolved dependencies.
Count dependencies by classification:
internal_count-- dependencies already satisfied within the selectionexternal_selected_count-- dependencies in selected groups but not individually selectedexternal_missing_count-- dependencies not in any selected groupexternal_count-- non-component external dependencies (MCP servers, scripts)system_count-- Claude Code platform dependencies
If external_selected_count == 0 AND external_missing_count == 0 AND external_count == 0:
The selection is fully self-contained. Display a brief confirmation and skip to Step 5:
All dependencies resolved -- no missing cross-plugin references.
{internal_count} internal dependencies found between selected components.
Otherwise, proceed to Step 4.
Step 4: Alert on Missing Dependencies
Present the dependency analysis to the user, organized by category:
## Dependency Analysis
**Components scanned:** {SELECTED_COMPONENTS.length}
**Total dependencies found:** {DEPENDENCIES.length}
**Internal (resolved):** {internal_count}
**Missing component dependencies:** {external_selected_count + external_missing_count}
**External (manual porting needed):** {external_count}
**System (Claude Code platform):** {system_count}
{If external_selected_count + external_missing_count > 0:}
### Missing Component Dependencies
These selected components depend on components not in your selection:
| Source Component | Depends On | Dependency Type | Group | Reference Pattern |
|---|---|---|---|---|
| {source.name} | {target_ref} | {dep_type} | {target_group} | `{raw_pattern snippet}` |
{If any dependency has transitive: true:}
Note: Dependencies marked with (*) are transitive -- discovered by following dependency chains beyond the initial selection.
{If external_count > 0:}
### External Dependencies (Manual Porting Required)
These dependencies cannot be automatically ported and will require manual setup on the target platform:
| Source Component | External Dependency | Type | Notes |
|---|---|---|---|
| {source.name} | {target_ref} | MCP server / bash script | Requires manual configuration |
These will be documented in the gap report with setup instructions.
4a: Resolve Missing Component Dependencies
If there are missing component dependencies (external_selected_count + external_missing_count > 0):
Use AskUserQuestion to let the user decide:
AskUserQuestion:
questions:
- header: "Missing Dependencies"
question: "Some selected components depend on {external_selected_count + external_missing_count} components not in your selection. How would you like to handle this?"
options:
- label: "Add missing dependencies"
description: "Include {count} additional components to resolve all references"
- label: "Proceed without them"
description: "Continue -- missing references will be flagged in the gap report"
- label: "Go back to selection"
description: "Return to component selection to adjust"
multiSelect: false
If "Add missing dependencies":
- For each
External-selecteddependency: locate the component in its group directory, build its component entry (type, group, name, path), and add toSELECTED_COMPONENTS - For each
External-missingdependency: scan the component from disk using the component scanning conventions, build its entry, and add toSELECTED_COMPONENTS - Re-run Steps 1 and 2 to capture any new transitive dependencies introduced by the added components
- Repeat the self-contained check (Step 3). If new missing dependencies are found, present Step 4 again. Continue until either the selection is self-contained or the user chooses to proceed without remaining dependencies.
If "Go back to selection": Return to Phase 2 Step 2.
If "Proceed without them": Continue to Step 5. Missing dependencies will be tracked as entries in CONVERSION_GAPS during Phase 5.
4b: Report Circular References
If circular references were detected (from Step 2d):
Display a warning after the missing dependencies resolution:
### Circular References Detected
WARNING: {CIRCULAR_REFS.length} circular dependency chain(s) found:
{For each cycle in CIRCULAR_REFS:}
- {cycle[0]} -> {cycle[1]} -> ... -> {cycle[0]}
These will be handled during conversion (Phase 5) using topological sort with cycle-breaking.
The component with the fewest incoming dependencies in each cycle will be processed first.
Circular references do not require user action -- they are informational warnings. Proceed to Step 5.
Step 5: Dependency Graph Summary
Build the final dependency graph summary and compute the conversion order for Phase 5.
5a: Topological Sort
Compute a dependency-sorted conversion order:
- Start with components that have zero unresolved dependencies (leaf nodes with no outgoing edges to other selected components)
- Process in layers: each layer contains components whose dependencies are all in previous layers
- Cycle-breaking: For components involved in circular references, break each cycle by placing the component with the fewest incoming edges first, then continue the sort normally
- Within each layer, sort alphabetically by
{type}:{group}/{name}for deterministic ordering
Store the sorted list as CONVERSION_ORDER.
5b: Display Summary
## Dependency Graph
**Components:** {SELECTED_COMPONENTS.length}
**Internal dependencies:** {internal_count}
**External dependencies (to be flagged):** {external_count + external_missing_count}
**Circular references:** {CIRCULAR_REFS.length or "none"}
**System dependencies:** {system_count} Claude Code platform features
Conversion order (dependency-sorted):
1. {component_id} -- no dependencies
2. {component_id} -- depends on: {dep1}, {dep2}
3. {component_id} -- depends on: {dep1}
...
5c: Store Dependency Graph
Store the complete graph as DEPENDENCY_GRAPH for consumption by Phase 5:
DEPENDENCY_GRAPH = {
nodes: SELECTED_COMPONENTS,
edges: DEPENDENCIES,
circular_refs: CIRCULAR_REFS,
conversion_order: CONVERSION_ORDER,
external_deps: [entries where dep_type == "external"],
classification_counts: { internal, external_selected, external_missing, external, system }
}
Phase 4: Platform Research
Goal: Spawn a research subagent to investigate the target platform's current plugin architecture, compare findings against the existing adapter file, and produce a merged knowledge base for conversion.
Step 1: Prepare Research Context
Before spawning the research agent, gather the context it needs:
-
Count selected components by type from
SELECTED_COMPONENTS:skill_count— number of skill componentsagent_count— number of agent componentshook_count— number of hooks componentsref_count— total reference files across all selected skillsmcp_count— number of MCP config components
-
Extract adapter content (if
ADAPTERexists):- Read the full content of the adapter file at
${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md - Store the raw content as
ADAPTER_CONTENTfor inclusion in the research prompt - Extract the adapter's
target_platform_versionfield from the Adapter Version section
- Read the full content of the adapter file at
-
Build component summary — a brief list of what is being ported, to help the research agent focus on relevant platform features:
Components to convert: - Skills: {list of skill names} - Agents: {list of agent names with model tiers} - Hooks: {yes/no, with event types if yes} - References: {count} files - MCP configs: {yes/no, with server names if yes} Key features used by these components: - {e.g., "Task tool for subagent spawning (used by deep-analysis)"} - {e.g., "AskUserQuestion for interactive workflows (used by create-spec)"} - {e.g., "Cross-plugin composition via ${CLAUDE_PLUGIN_ROOT}/../ paths"}
Step 2: Launch Research Agent
Spawn the research agent using the Task tool with subagent_type: "researcher" and model: "sonnet":
Task tool prompt:
"Research the plugin/extension system for: {TARGET_PLATFORM}
You are researching this platform to support converting Agent Alchemy (Claude Code) plugins to {TARGET_PLATFORM} format. The conversion needs to handle {skill_count} skills, {agent_count} agents, {hook_count} hook configs, {ref_count} reference files, and {mcp_count} MCP configs.
{If ADAPTER exists:}
## Existing Adapter File
An adapter file already exists for this platform. Here is its full content:
---BEGIN ADAPTER---
{ADAPTER_CONTENT}
---END ADAPTER---
IMPORTANT: Compare your research findings against every mapping in this adapter file. In your Adapter Comparison section:
- Flag any mappings that appear outdated based on your research
- Identify new platform features or changes not covered by the adapter
- Note the adapter's platform version ({adapter_platform_version}) vs. the current version you find
- For each stale or missing mapping, provide the corrected/new mapping
{If ADAPTER is null:}
## No Existing Adapter
No adapter file exists for this platform yet. Research from scratch and produce a comprehensive platform profile. Your findings will be the primary source of truth for the conversion engine.
## Components Being Ported
{component_summary from Step 1}
## Research Focus Areas
Investigate these areas thoroughly — they directly affect conversion quality:
1. **Plugin directory structure**: Where plugins live, file naming conventions, required files
2. **Configuration format**: YAML, JSON, TOML, or other formats for plugin metadata
3. **Tool/capability equivalents**: What built-in tools does the platform provide? Map against Claude Code's tools (Read, Write, Edit, Glob, Grep, Bash, Task, WebSearch, WebFetch, AskUserQuestion)
4. **Model configuration**: How are AI models specified? Does the platform support model tiers or selection?
5. **Lifecycle hooks**: Does the platform have pre/post execution hooks? Event system?
6. **Composition mechanism**: How do plugins load or reference other plugins? Is there an equivalent to skill composition via prompt injection?
7. **Path resolution**: Equivalent of ${CLAUDE_PLUGIN_ROOT} for resolving plugin-relative paths
8. **Agent/subagent support**: Can plugins spawn sub-tasks or sub-agents? How?
9. **User interaction**: How do plugins prompt the user for input during execution?
10. **MCP integration**: Does the platform support Model Context Protocol servers?
Return a structured platform profile following your output format specification. Include confidence levels for every finding."
Retry logic: If the Task tool call fails (agent error, timeout, or empty response), retry once automatically. If the retry also fails, proceed to the research failure handling in Step 5.
Step 3: Process Research Findings
When the research agent returns its platform profile:
-
Parse the structured platform profile from the response. Extract these sections:
- Research Summary (documentation quality, sources consulted, overall confidence)
- Plugin System Overview
- Directory Structure
- File Format
- Tool Equivalents table
- Model Tier Mappings table
- Composition Patterns
- Lifecycle Hooks
- Known Limitations
- Adapter Comparison (if adapter was provided)
- Sources list
-
Store as
RESEARCH_FINDINGS— the parsed profile is available throughout the remaining phases for the conversion engine to reference. -
Merge research with adapter into
CONVERSION_KNOWLEDGE:The conversion engine uses a merged knowledge base called
CONVERSION_KNOWLEDGEthat combines the adapter file and research findings with clear precedence rules:Category Precedence Rule Tool name mappings Adapter takes precedence for established mappings; research fills gaps where adapter has nullor no entryModel tier mappings Adapter takes precedence; research supplements with version-specific notes Platform version info Research always takes precedence (it is fresher) Directory structure Research takes precedence if it differs from adapter (platform may have changed) Composition patterns Research takes precedence if it provides more detail; adapter is baseline Lifecycle hooks Research takes precedence if it finds new hook types; adapter is baseline Known limitations Union of both — all limitations from adapter AND research are tracked Path resolution Research takes precedence if adapter mapping is marked as uncertain When adapter and research agree on a mapping, mark it as
confidence: high. When only one source provides a mapping, mark it asconfidence: medium. When adapter and research disagree, mark it asconfidence: conflictand flag for user resolution in Step 4. -
Check for adapter staleness:
Initialize
STALENESS_STATUSto track the result for migration guide logging:STALENESS_STATUS = { checked: false, adapter_version: null, adapter_platform_version: null, research_platform_version: null, is_stale: false, is_unversioned: false, research_has_version: false, stale_mappings: [], new_features: [], user_decision: null, error: null }Wrap the entire staleness check in error-safe logic. If any step below fails (parsing error, unexpected format, etc.), set
STALENESS_STATUS.errorto a description of the failure, log a warning ("Staleness check encountered an error: {error}. Proceeding with conversion."), and continue to Step 4. The staleness check must never block the conversion workflow.If
ADAPTERexists:a. Read adapter version fields from the Adapter Version section of the adapter file:
- Extract
adapter_version(the adapter file's own version, e.g.,1.0.0) - Extract
target_platform_version(the platform version the adapter was written for, e.g.,0.0.55) - Set
STALENESS_STATUS.checked = true - If neither field is found, set
STALENESS_STATUS.is_unversioned = trueand log a warning: "Adapter file for {TARGET_PLATFORM} has no version fields. Staleness cannot be determined — proceeding with adapter as-is."
b. Check if research reported a platform version:
- Look for a version in the research findings (Platform Overview, Research Summary, or version-related fields)
- If research did not report a version, set
STALENESS_STATUS.research_has_version = falseand log a note: "Research did not report a specific platform version for {TARGET_PLATFORM}. Skipping version comparison." - If research reported a version, set
STALENESS_STATUS.research_has_version = trueand store it inSTALENESS_STATUS.research_platform_version
c. Compare versions (only if both adapter and research have version information):
- Perform version comparison using these rules:
- Exact match: If
target_platform_versionequalsresearch_platform_versionexactly, versions match —STALENESS_STATUS.is_stale = false - Semantic version comparison: If both versions follow semver format (e.g.,
0.0.55,1.2.3), compare numerically. If research version is newer, setSTALENESS_STATUS.is_stale = true - Fuzzy comparison: If version formats differ (e.g., adapter has
0.0.55but research reportsv0.0.55,0.0.55-beta, or a date-based version), attempt normalization:- Strip leading
vorVprefix - Strip trailing pre-release suffixes (
-alpha,-beta,-rc.1, etc.) for comparison - If normalized versions match, treat as matching
- If normalization fails or formats are incomparable, set
STALENESS_STATUS.is_stale = true(err on the side of warning) and note: "Version format mismatch — adapter: '{adapter_version}', research: '{research_version}'. Treating as potentially stale."
- Strip leading
- Exact match: If
d. Collect stale mappings and new features (regardless of version match, if research provides an Adapter Comparison section):
- If the Adapter Comparison section flags outdated mappings, collect them as
STALE_MAPPINGSand store inSTALENESS_STATUS.stale_mappings - If the research found new platform features not in the adapter, collect them as
NEW_FEATURESand store inSTALENESS_STATUS.new_features - If stale mappings or new features exist even when versions match, set
ADAPTER_STALE = true(content staleness despite version match)
- Extract
Step 4: Resolve Conflicts
If any mappings in CONVERSION_KNOWLEDGE are marked as confidence: conflict:
-
Build a conflict list summarizing each disagreement:
Conflicts found between adapter file and research findings: 1. {mapping_name}: - Adapter says: {adapter_value} - Research says: {research_value} (source: {url}) - Impact: {which components are affected} 2. {mapping_name}: ... -
Present conflicts to user via AskUserQuestion for each conflict (or batch if fewer than 5):
AskUserQuestion: questions: - header: "Research Conflict" question: "The adapter file and fresh research disagree on {mapping_name}. Which should be used for conversion?" options: - label: "Use research finding" description: "{research_value} — from {source}, researched today" - label: "Use adapter mapping" description: "{adapter_value} — from adapter file v{adapter_version}" - label: "Skip this mapping" description: "Flag as unresolved in the gap report" multiSelect: false -
Apply resolutions to
CONVERSION_KNOWLEDGE:- "Use research finding": Update the mapping to the research value, set
confidence: high, marksource: research - "Use adapter mapping": Keep the adapter value, set
confidence: high, marksource: adapter - "Skip this mapping": Set
confidence: unresolved, will appear in the gap report
- "Use research finding": Update the mapping to the research value, set
If there are no conflicts, skip this step entirely.
Step 5: Present Research Summary
Display a summary of the research findings and merged knowledge to the user:
## Platform Research: {TARGET_PLATFORM}
**Documentation quality:** {research_summary.documentation_quality}
**Sources consulted:** {research_summary.sources_consulted}
**Overall confidence:** {research_summary.overall_confidence}
### Key Findings
- **Plugin format:** {file_format description}
- **Tool equivalents:** {matched_count}/{total_count} Claude Code tools have equivalents
- **Model support:** {model_tier_summary}
- **Composition:** {composition_patterns summary}
- **Hooks:** {lifecycle_hooks summary — supported/not supported/partial}
- **Agent spawning:** {agent/subagent support summary}
- **User interaction:** {user interaction mechanism summary}
### Knowledge Sources for Conversion
- Adapter file mappings: {count} mappings
- Research-supplemented mappings: {count} new/updated mappings
- Conflicts resolved: {count}
- Unresolved gaps: {count}
{If STALENESS_STATUS.is_unversioned = true:}
### Adapter Version Notice
NOTE: The adapter file for {TARGET_PLATFORM} has no version fields. Staleness cannot be determined. The adapter will be used as-is, supplemented by research findings.
{If STALENESS_STATUS.research_has_version = false AND ADAPTER exists:}
### Research Version Notice
NOTE: Research did not report a specific platform version for {TARGET_PLATFORM}. Version comparison was skipped. The adapter's target_platform_version ({STALENESS_STATUS.adapter_platform_version}) is assumed current.
{If STALENESS_STATUS.error:}
### Staleness Check Notice
NOTE: The staleness check encountered an error: {STALENESS_STATUS.error}. Conversion will proceed using available adapter and research data.
{If ADAPTER_STALE = true:}
### Adapter Staleness Warning
WARNING: The existing adapter file targets {TARGET_PLATFORM} v{STALENESS_STATUS.adapter_platform_version}, but research found the current version is v{STALENESS_STATUS.research_platform_version}.
Stale mappings detected:
{For each stale mapping in STALENESS_STATUS.stale_mappings:}
- {mapping_name}: adapter says "{old_value}", research found "{new_value}"
New platform features not in adapter:
{For each new feature in STALENESS_STATUS.new_features:}
- {feature_name}: {description}
{If no ADAPTER:}
### New Platform Profile
Research produced a fresh platform profile since no adapter file existed.
Consider saving a new adapter file from these findings after conversion.
After displaying the summary, if ADAPTER_STALE = true, present the user with options via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Adapter Staleness"
question: "The adapter file for {TARGET_PLATFORM} appears to be stale (adapter targets v{STALENESS_STATUS.adapter_platform_version}, research found v{STALENESS_STATUS.research_platform_version}). {stale_mapping_count} mappings may be outdated and {new_feature_count} new platform features were found. How would you like to proceed?"
options:
- label: "Proceed with existing adapter"
description: "Continue conversion — research findings will supplement and override stale adapter mappings via CONVERSION_KNOWLEDGE precedence rules"
- label: "Update adapter file first"
description: "Pause conversion to update the adapter file with research findings, then resume"
multiSelect: false
Handle each choice:
-
"Proceed with existing adapter": Set
STALENESS_STATUS.user_decision = "proceed". Continue to Phase 5 usingCONVERSION_KNOWLEDGEas already merged (research takes precedence for stale mappings per the precedence rules in Step 3). Log: "User chose to proceed with existing adapter. Research findings will supplement stale mappings during conversion." -
"Update adapter file first": Set
STALENESS_STATUS.user_decision = "update". Before continuing to Phase 5:- Read the current adapter file at
${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md - Apply research findings to update stale mappings in-place:
- For each entry in
STALE_MAPPINGS: update the mapping value in the adapter to match the research finding - For each entry in
NEW_FEATURES: add the feature to the appropriate adapter section - Update the
target_platform_versionfield to the research-reported version - Update the
last_updatedfield to today's date - Increment the
adapter_versionpatch number (e.g.,1.0.0->1.0.1) - Append to the
changelogfield describing the update
- For each entry in
- Write the updated adapter file
- Re-read the updated adapter as
ADAPTERand re-merge intoCONVERSION_KNOWLEDGE - Log: "Adapter file updated to target {TARGET_PLATFORM} v{research_platform_version}. Conversion will use updated mappings."
- Read the current adapter file at
If STALENESS_STATUS.is_unversioned = true and stale mappings or new features were found, also present the AskUserQuestion above (since content can be stale even without version fields).
Record staleness status for migration guide:
Store STALENESS_STATUS for inclusion in the migration guide output (Phase 6). The migration guide should include a "Platform Adapter Status" section documenting:
- Whether a staleness check was performed
- Adapter version vs. research-reported version (if available)
- Whether the adapter was stale, unversioned, or current
- What decision the user made (proceed or update)
- Any stale mappings that were identified
- Any new features discovered by research
Step 6: Handle Research Failure
If the research agent failed (both initial attempt and retry):
-
Inform the user of what happened:
The platform research agent was unable to complete its investigation. Reason: {error_message or "timeout/empty response"} -
Offer recovery options via AskUserQuestion:
AskUserQuestion: questions: - header: "Research Issue" question: "The platform research agent encountered an issue: {brief_reason}. How would you like to proceed?" options: - label: "Retry research" description: "Launch the research agent again (attempt {retry_count + 1})" - label: "Use adapter only" description: "Proceed with existing adapter file mappings (no fresh research)" - label: "Cancel" description: "Exit the porter" multiSelect: false -
Handle each choice:
-
"Retry research": Return to Step 2 and re-launch the research agent. Allow up to 2 total retries (3 attempts total).
-
"Use adapter only":
- If
ADAPTERexists: SetRESEARCH_FINDINGS = null. SetCONVERSION_KNOWLEDGEto adapter mappings only withconfidence: mediumon all entries (no research validation). Inform the user: "Proceeding with adapter file mappings only. Conversion quality may be affected — adapter mappings have not been validated against current platform documentation." Continue to Phase 5. - If
ADAPTERis null: Inform the user: "Cannot proceed — no adapter file exists and research failed. The conversion engine requires at least one source of platform knowledge." Offer:AskUserQuestion: questions: - header: "No Platform Knowledge Available" question: "Neither an adapter file nor research findings are available. What would you like to do?" options: - label: "Retry research" description: "Try the research agent one more time" - label: "Cancel" description: "Exit the porter — conversion cannot proceed without platform knowledge" multiSelect: false
- If
-
"Cancel": End the workflow gracefully with a summary of what was completed so far.
-
Phase 4.5: Dry-Run Preview
Goal: Offer an optional preview of expected conversion output -- showing the target file tree, per-component conversion status, expected issues, and estimated fidelity -- without writing any files or running the full conversion engine.
This phase consumes SELECTED_COMPONENTS, DEPENDENCY_GRAPH (from Phase 3), and CONVERSION_KNOWLEDGE (from Phase 4). It does not modify any of these structures.
Step 1: Offer Dry-Run Preview
If DRY_RUN = true (set via --dry-run flag): Skip the offer and proceed directly to Step 2 (preview is mandatory).
If DRY_RUN = false: Use AskUserQuestion to offer the preview as an optional step:
AskUserQuestion:
questions:
- header: "Dry-Run Preview"
question: "Would you like to preview the expected conversion output before proceeding? This shows the target file tree, per-component status, and expected issues without writing any files."
options:
- label: "Run preview"
description: "Generate and display a dry-run preview of the conversion"
- label: "Skip preview and convert"
description: "Proceed directly to interactive conversion (Phase 5)"
multiSelect: false
If "Skip preview and convert": Skip the rest of Phase 4.5 and proceed directly to Phase 5.
If "Run preview": Continue to Step 2.
Step 2: Generate Preview
Generate the preview by analyzing CONVERSION_KNOWLEDGE mappings against each component in SELECTED_COMPONENTS. This step predicts conversion outcomes without running the full conversion engine.
Wrap the entire preview generation in error-safe logic. If any step below fails (parsing error, unexpected format, etc.), log a warning ("Preview generation encountered an error: {error}. You can still proceed with conversion."), skip to Step 4 (user decision), and offer the option to proceed with conversion despite the preview failure.
2a: Build Target File Tree
For each component in SELECTED_COMPONENTS, predict the output file path using CONVERSION_KNOWLEDGE:
-
Skills: Map source path
claude/{group}/skills/{name}/SKILL.mdto target path using directory structure mappings:- Check
CONVERSION_KNOWLEDGEforskill_file_patternin directory structure mappings - If
skill_file_patternis defined (e.g.,{name}/SKILL.md): expand the pattern by replacing{name}with the skill name (applyingnaming_convention), then build path:{plugin_root}/{skill_dir}/{expanded_pattern}(e.g.,.opencode/skills/deep-analysis/SKILL.md) - If no
skill_file_pattern: applynaming_conventionandfile_extensionfor a flat filename, then build path:{plugin_root}/{skill_dir}/{converted_filename}
- Check
-
Agents: Map source path
claude/{group}/agents/{name}.mdto target path:- If the target platform has an agent concept:
{plugin_root}/{agent_dir}/{converted_filename} - If no agent concept (adapter maps agent type to
nullor alternative): note the mapping strategy (e.g., "merged into skill" or "mapped to fixed type")
- If the target platform has an agent concept:
-
Hooks: Map
claude/{group}/hooks/hooks.jsonto the target hooks format:- If target supports hooks:
{plugin_root}/{hook_dir}/{target_hook_filename} - If no hook support: note as "unsupported -- will be documented in gap report"
- If target supports hooks:
-
References: For each reference file in selected skills'
references/directories:- If target supports reference directories:
{plugin_root}/{reference_dir}/{filename} - If no reference support (composition is
noneorinline): note as "will be inlined into parent skill"
- If target supports reference directories:
-
MCP configs: Map
claude/{group}/.mcp.jsonto the target MCP format:- If target supports MCP:
{plugin_root}/{config_dir}/{target_mcp_filename} - If no MCP support: note as "unsupported -- will be documented in gap report"
- If target supports MCP:
Store the predicted paths as PREVIEW_FILE_TREE -- a list of entries, each containing: { source_path, target_path, component_type, component_name, mapping_strategy }.
2b: Predict Per-Component Conversion Status
For each component, estimate its conversion status by analyzing how well CONVERSION_KNOWLEDGE covers the component's features:
- Read the component source file (already loaded during Phase 2/3)
- Count mappable features:
- Frontmatter fields: count fields, check how many have non-null mappings in frontmatter mappings
- Tool references: count tools in
allowed-toolsand body, check how many have non-null mappings in tool name mappings - Composition references: count
${CLAUDE_PLUGIN_ROOT}patterns, check if composition mechanism is notnone - Path references: count path patterns, check if path resolution root variable is not null
- User interaction patterns: count
AskUserQuestionreferences, check if a mapping exists
- Classify the component:
- Count
supported(non-null mapping exists),partial(mapping ispartial:*or workaround-dependent), andunsupported(mapping isnull) features - Apply fidelity estimation to calculate a score range:
optimistic_score = ((supported + partial) * 1.0 + unsupported * 0.0) / total * 100 pessimistic_score = ((supported * 1.0) + (partial * 0.7) + (unsupported * 0.0)) / total * 100 - Determine predicted status:
- Both scores >= 80:
"Full"-- component is highly portable - Pessimistic >= 50:
"Partial"-- component works but with limitations - Pessimistic < 50:
"Unsupported"-- significant gaps, may not be worthwhile
- Both scores >= 80:
- Count
Store predictions as PREVIEW_STATUS -- a list of entries, each containing: { component_name, component_type, group, supported_count, partial_count, unsupported_count, total_count, optimistic_score, pessimistic_score, predicted_status }.
2c: Collect Expected Issues
For each component, identify expected issues from the mapping analysis:
- Null tool mappings: List tools that map to
nullin tool name mappings - Null frontmatter fields: List fields that map to
nullin frontmatter mappings - Unsupported composition: Flag if composition mechanism is
noneand component uses composition - Unsupported hooks: Flag if hook events map to
nullin hook event mappings - Missing cross-plugin support: Flag if component uses cross-plugin references and composition does not support cross-plugin
- No user interaction equivalent: Flag if component uses
AskUserQuestionand the mapping isnull
Group issues by severity:
- Critical: Features essential to the component's core function (e.g., Task tool for hub-and-spoke skills)
- Functional: Features that affect behavior but the component can work without them (e.g., specific tool references)
- Cosmetic: Minor formatting or metadata differences (e.g., omitted frontmatter fields)
Store as PREVIEW_ISSUES -- a list of entries, each containing: { component_name, feature, severity, reason, adapter_notes }.
2d: Calculate Estimated Fidelity Range
Compute an overall estimated fidelity range across all components:
overall_optimistic = sum(component.optimistic_score * component.weight) / sum(component.weight)
overall_pessimistic = sum(component.pessimistic_score * component.weight) / sum(component.weight)
Where weight is the same as Phase 5 Step 9:
skill= 3,agent= 2,hooks= 1,reference= 1,mcp= 1
Round both scores to the nearest integer.
Step 3: Display Preview
Present the preview in a structured format.
Large plugin group handling: If SELECTED_COMPONENTS has more than 20 components, summarize the file tree by grouping files by directory rather than listing every individual file. Show the directory structure with file counts per directory instead.
## Dry-Run Preview: {TARGET_PLATFORM}
**Components:** {SELECTED_COMPONENTS.length}
**Estimated fidelity:** {overall_pessimistic}% - {overall_optimistic}%
### Target File Tree
{If 20 or fewer components:}
{target_root}/
{For each entry in PREVIEW_FILE_TREE, sorted by target_path:}
{target_path} <- {source_path} [{mapping_strategy}]
{If more than 20 components:}
{target_root}/
{skill_dir}/ ({skill_count} files)
{agent_dir}/ ({agent_count} files)
{hook_dir}/ ({hook_count} files)
{reference_dir}/ ({ref_count} files)
{config_dir}/ ({config_count} files)
### Per-Component Conversion Status
| Component | Type | Group | Status | Fidelity Estimate | Issues |
|-----------|------|-------|--------|-------------------|--------|
{For each entry in PREVIEW_STATUS:}
| {component_name} | {component_type} | {group} | {predicted_status} | {pessimistic_score}% - {optimistic_score}% | {issue_count} |
{If all components have predicted_status == "Unsupported":}
### Warning: All Components Unsupported
All selected components are predicted to have significant conversion gaps on {TARGET_PLATFORM}. The overall estimated fidelity is {overall_pessimistic}% - {overall_optimistic}%. Conversion may not produce useful output. Consider:
- Selecting a different target platform
- Selecting fewer, simpler components
- Reviewing the gap details below before proceeding
### Expected Issues
{If PREVIEW_ISSUES is empty:}
No significant issues detected. All features have direct or partial mappings.
{If PREVIEW_ISSUES is not empty:}
{Group by severity, show critical first:}
**Critical ({critical_count}):**
{For each critical issue:}
- **{component_name}**: `{feature}` -- {reason}{If adapter_notes: " ({adapter_notes})"}
**Functional ({functional_count}):**
{For each functional issue:}
- **{component_name}**: `{feature}` -- {reason}
**Cosmetic ({cosmetic_count}):**
{For each cosmetic issue:}
- **{component_name}**: `{feature}` -- {reason}
### Estimated Fidelity
**Overall:** {overall_pessimistic}% - {overall_optimistic}% (weighted by component complexity)
The fidelity range reflects the best-case (all partial mappings succeed fully) and worst-case (partial mappings contribute reduced fidelity) scenarios. The actual score will be determined during interactive conversion when incompatibilities are resolved.
Step 4: User Decision
After displaying the preview, present the user with a decision via AskUserQuestion.
If DRY_RUN = true (invoked with --dry-run flag):
AskUserQuestion:
questions:
- header: "Dry-Run Complete"
question: "The dry-run preview is complete. No files were written. Would you like to proceed with the actual conversion?"
options:
- label: "Proceed with conversion"
description: "Continue to Phase 5 (Interactive Conversion) and convert the selected components"
- label: "Done"
description: "Exit the porter -- preview only"
multiSelect: false
If DRY_RUN = false (preview was offered and accepted):
AskUserQuestion:
questions:
- header: "Preview Complete"
question: "Preview complete. Proceed with interactive conversion?"
options:
- label: "Proceed with conversion"
description: "Continue to Phase 5 and convert the selected components"
- label: "Cancel"
description: "Exit the porter"
multiSelect: false
Handle choices:
- "Proceed with conversion": Set
DRY_RUN = false(in case it was true). Continue to Phase 5. - "Done" or "Cancel": End the workflow gracefully. Display a brief summary:
Porter exited after dry-run preview. No files were written. Components analyzed: {count} Estimated fidelity: {overall_pessimistic}% - {overall_optimistic}%
Phase 5: Wave-Based Conversion
Goal: Convert each selected component using a wave-based agent team, where each port-converter agent (Sonnet) handles a single component in an isolated context. The orchestrator (this skill, Opus) manages session files, spawns agent waves, resolves incompatibilities between waves, and consolidates results.
This phase consumes SELECTED_COMPONENTS, CONVERSION_ORDER, DEPENDENCY_GRAPH, and CONVERSION_KNOWLEDGE from Phases 2-4.
Step 1: Initialize Session
Create the session directory and write shared files that converter agents will read.
1a: Create Session Directory
mkdir -p .claude/sessions/__port_live__/results
If .claude/sessions/__port_live__/ already exists (stale session from a previous interrupted run):
- Archive the stale session:
mv .claude/sessions/__port_live__ .claude/sessions/port-interrupted-{YYYYMMDD}-{HHMMSS} - Recreate:
mkdir -p .claude/sessions/__port_live__/results - Log: "Archived stale porting session to .claude/sessions/port-interrupted-{timestamp}/"
1b: Serialize Conversion Knowledge
Write CONVERSION_KNOWLEDGE to .claude/sessions/__port_live__/conversion_knowledge.md following the format specified in ${CLAUDE_PLUGIN_ROOT}/skills/port-plugin/references/session-format.md.
The file contains all 9 adapter mapping sections (tool names, model tiers, skill frontmatter, agent frontmatter, hook events, directory structure, composition mechanism, path resolution, known limitations) serialized as markdown tables and key-value sections.
This file is written once and not modified during conversion.
1c: Serialize Dependency Graph
Write DEPENDENCY_GRAPH to .claude/sessions/__port_live__/dependency_graph.md following the session format reference.
Include: conversion order with wave assignments, dependency edges, circular references (if any), external dependencies, and classification counts.
This file is written once and not modified during conversion.
1d: Initialize Resolution Cache
Write an empty resolution cache to .claude/sessions/__port_live__/resolution_cache.md:
# Resolution Cache
## Cached Decisions
Update Ported Plugin
Apply incremental updates to previously-ported plugins when source plugins have changed or the target platform has evolved. Reads the PORT-METADATA embedded in MIGRATION-GUIDE.md to determine the baseline, detects source diffs and platform drift, and applies targeted updates without re-running the full port-plugin workflow.
CRITICAL: Complete ALL 5 phases. The workflow is not complete until Phase 5: Output & Refresh 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. Text output is only for status updates and informational summaries.
Plan Mode Behavior
CRITICAL: This skill performs an interactive update workflow, NOT an implementation plan. Proceed with the full detection and update workflow immediately -- do not defer to an "execution phase".
Phase Overview
Execute these phases in order, completing ALL of them:
- Load Context -- Parse arguments, locate MIGRATION-GUIDE.md, extract and validate PORT-METADATA
- Detect Changes -- Diff source files against baseline commit, check platform adapter staleness
- Apply Source Changes -- Incrementally update ported files for source modifications
- Apply Platform Changes -- Update ported files for platform adapter drift
- Output & Refresh -- Write files, refresh metadata, update history, and summarize
Phase 1: Load Context
Goal: Parse arguments, locate the MIGRATION-GUIDE.md from a previous port, extract the PORT-METADATA block, and validate that the baseline is intact.
Step 1: Parse Arguments
Parse $ARGUMENTS for:
--target <platform>-- Target platform slug (default:opencode)--source-only-- Only detect and apply source changes; skip platform change detection--platform-only-- Only detect and apply platform changes; skip source change detection--output-dir <path>-- Override output directory for updated files (default: write in-place)
Set TARGET_PLATFORM, SOURCE_ONLY, PLATFORM_ONLY, and OUTPUT_DIR from parsed arguments. If both --source-only and --platform-only are specified, they are mutually exclusive -- inform the user and proceed with full update (both flags false).
Step 2: Load Settings
Check .claude/agent-alchemy.local.md for a plugin-tools section (default-target, default-output-dir). Apply settings as defaults -- CLI arguments override.
Step 3: Locate MIGRATION-GUIDE.md
Search order: (1) {OUTPUT_DIR}/MIGRATION-GUIDE.md if specified, (2) ported/{TARGET_PLATFORM}/MIGRATION-GUIDE.md, (3) Glob: **/MIGRATION-GUIDE.md.
If multiple found, present for selection:
AskUserQuestion:
questions:
- header: "Multiple Migration Guides Found"
question: "Multiple MIGRATION-GUIDE.md files were found. Which one should be updated?"
options:
- label: "{path_1}"
description: "Last modified: {date}"
- label: "{path_2}"
description: "Last modified: {date}"
multiSelect: false
If none found, offer options via AskUserQuestion: "Run /port-plugin" (start fresh), "Specify path manually", or "Cancel". Handle accordingly. Store the located path as MIGRATION_GUIDE_PATH and its parent as PORT_OUTPUT_DIR.
Step 4: Extract PORT-METADATA
Read the MIGRATION-GUIDE.md file and extract the PORT-METADATA HTML comment block:
Read: {MIGRATION_GUIDE_PATH}
Search for the <!-- PORT-METADATA ... PORT-METADATA --> block and parse the YAML-like content to extract: source_commit, port_date, adapter_version, target_platform, target_platform_version, and components list (each with source, target, fidelity).
Error handling -- Missing metadata block:
AskUserQuestion:
questions:
- header: "Missing PORT-METADATA"
question: "The MIGRATION-GUIDE.md does not contain a PORT-METADATA block. How would you like to proceed?"
options:
- label: "Reconstruct metadata"
description: "Scan the output directory and git history to rebuild the metadata block"
- label: "Run fresh port"
description: "Start over with /port-plugin"
- label: "Cancel"
description: "Exit the update workflow"
multiSelect: false
If reconstructing: scan PORT_OUTPUT_DIR for converted files via Glob, find the most recent port commit via git log --oneline --all -- {MIGRATION_GUIDE_PATH}, and build best-effort metadata. Warn user it may be incomplete.
Error handling -- Malformed metadata: Fall back to line-by-line regex extraction of key-value pairs and - source: / target: / fidelity: patterns. If fallback fails, present the reconstruction option.
Store extracted metadata as PORT_METADATA.
Step 5: Validate Baseline
Verify the baseline is intact:
- Source commit:
git rev-parse --verify {PORT_METADATA.source_commit}-- if not found, setSOURCE_COMMIT_VALID = falseand warn - Source files: Check each
component.sourcestill exists; buildMISSING_SOURCESlist - Target files: Check each
{PORT_OUTPUT_DIR}/{component.target}still exists; buildMISSING_TARGETSlist - Adapter file: Verify
${CLAUDE_PLUGIN_ROOT}/references/adapters/{PORT_METADATA.target_platform}.mdexists
Step 6: Display Summary and Confirm
Present the baseline summary via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Port Baseline Summary"
question: |
Previous port details:
- Port date: {PORT_METADATA.port_date}
- Source commit: {PORT_METADATA.source_commit} (short hash)
- Components: {PORT_METADATA.components.length} ported
- Adapter version: {PORT_METADATA.adapter_version}
- Target platform: {PORT_METADATA.target_platform} v{PORT_METADATA.target_platform_version}
{If MISSING_SOURCES.length > 0:}
- WARNING: {MISSING_SOURCES.length} source file(s) no longer exist
{If MISSING_TARGETS.length > 0:}
- WARNING: {MISSING_TARGETS.length} target file(s) no longer exist
{If !SOURCE_COMMIT_VALID:}
- WARNING: Source commit not found in git history (history may have been rewritten)
Proceed with update check?
options:
- label: "Proceed"
description: "Check for source and platform changes since the last port"
- label: "View missing files"
description: "Show details of missing source or target files before proceeding"
- label: "Cancel"
description: "Exit the update workflow"
multiSelect: false
If "View missing files": list all missing files, then re-present proceed/cancel. If "Cancel": exit gracefully.
Phase 2: Detect Changes
Goal: Identify what has changed since the original port -- both in source plugin files and on the target platform -- and present a combined summary for the user to scope the update.
Run two parallel change detection tracks (unless --source-only or --platform-only was specified).
Track A: Source Changes
Skip this track if PLATFORM_ONLY is true.
Step A1: Diff Source Files
git diff {PORT_METADATA.source_commit}..HEAD -- {space-separated list of source paths}
If SOURCE_COMMIT_VALID is false, fall back to git log --since="{PORT_METADATA.port_date}" and diff each file against its state at the closest commit to the port date.
Step A2: Detect New and Deleted Files
git diff --name-status {PORT_METADATA.source_commit}..HEAD -- {source parent directories}
Parse output: A (new), D (deleted), M (modified, already in A1), R (renamed -- track both paths).
Step A3: Classify Changes
For each changed source file, classify the change into one of three categories:
| Classification | Examples | Action |
|---|---|---|
| Structural | Frontmatter changes, new/removed sections, tool list changes, new/removed AskUserQuestion blocks | Re-run conversion logic |
| Content | Prompt text modifications, instruction wording, reference path changes, code/table content | Targeted text transformation |
| Cosmetic | Whitespace, formatting, comment text, markdown styling changes | Auto-apply without prompting |
Build SOURCE_CHANGES list. Each entry: file_path, change_type (modified/added/deleted/renamed), classification (structural/content/cosmetic), diff_summary, diff_lines_added, diff_lines_removed, affected_sections, and component_entry (matching PORT-METADATA component, or null for new files).
New files get classification: "structural" and diff_summary: "New component -- requires full port". Deleted files get classification: "structural" and diff_summary: "Source component deleted -- ported version may be orphaned".
Track B: Platform Changes
Skip this track if SOURCE_ONLY is true.
Step B1: Load Validate-Adapter Skill
Read the validate-adapter skill to access its platform validation logic:
Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md
Step B2: Run Platform Validation
-
Load the adapter file:
Read: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md -
Spawn the researcher agent:
Task: description: "Research current state of {TARGET_PLATFORM}'s plugin system. Compare against adapter. Focus on changes since v{PORT_METADATA.target_platform_version}." subagent_type: "agent-alchemy-plugin-tools:researcher" input: | Target platform: {TARGET_PLATFORM} Existing adapter file: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md Last known platform version: {PORT_METADATA.target_platform_version} -
Collect the researcher's platform profile and adapter comparison results.
Step B3: Extract Platform Findings
From the researcher's adapter comparison results, extract three categories:
Categorize findings into three types:
| Type | Fields | Default Impact |
|---|---|---|
| stale | adapter_section, old_mapping, new_mapping, affected_components | breaking or cosmetic |
| missing | adapter_section, feature_description, potential_benefit | additive |
| removed | adapter_section, feature_description, alternative, affected_components | breaking |
Step B4: Classify Platform Impact
Classify each finding by cross-referencing against PORT_METADATA.components:
- Breaking: Stale/removed mapping used by at least one ported component
- Additive: New feature that could improve ported components but is not required
- Cosmetic: Naming change or minor adjustment with no functional impact
Build PLATFORM_CHANGES list from the classified findings.
Combined Change Summary
After both tracks complete, present the combined results via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Change Detection Summary"
question: |
Changes detected since the last port ({PORT_METADATA.port_date}):
Source changes:
- {count} files modified ({structural_count} structural, {content_count} content, {cosmetic_count} cosmetic)
- {added_count} new files detected
- {deleted_count} files deleted
Platform changes ({TARGET_PLATFORM}):
- {stale_count} stale mappings ({breaking_stale_count} breaking)
- {missing_count} new platform features
- {removed_count} removed features ({breaking_removed_count} breaking)
Estimated update scope: {small/medium/large}
How would you like to proceed?
options:
- label: "Apply all changes"
description: "Process both source and platform changes"
- label: "Source changes only"
description: "Apply only source file updates, skip platform changes"
- label: "Platform changes only"
description: "Apply only platform-related updates, skip source changes"
- label: "Select specific changes"
description: "Choose individual changes to apply"
- label: "Cancel"
description: "Exit without making changes"
multiSelect: false
Scope estimation:
- Small: 0-3 total changes, all cosmetic or content
- Medium: 4-10 total changes, or any structural source changes, or any additive platform changes
- Large: 10+ total changes, or any breaking platform changes, or any new/deleted source files
If user selects "Select specific changes", present a detailed checklist:
AskUserQuestion:
questions:
- header: "Select Changes to Apply"
question: "Select which changes to apply:"
options:
- label: "[source] {file_name} ({classification})"
description: "{diff_summary}"
- label: "[platform] {finding_type}: {description}"
description: "Impact: {impact} -- affects {affected_count} component(s)"
multiSelect: true
Store the user's selection as SELECTED_CHANGES with two sub-lists: selected_source_changes and selected_platform_changes.
If user selects "Cancel", exit gracefully.
Phase 3: Apply Source Changes
Goal: Incrementally update ported files to reflect source plugin modifications.
Skip this phase entirely if:
- User selected "Platform changes only" in Phase 2
- User selected "Cancel" in Phase 2
SOURCE_CHANGESis empty (no source changes detected)
Initialize tracking:
UPDATED_FILES = [] // files modified during this phase
SKIPPED_FILES = [] // files user chose to skip
NEW_COMPONENTS = [] // new source files that need full porting
DELETED_COMPONENTS = [] // source files deleted, ported versions potentially orphaned
Step 1: Apply Cosmetic Changes
Process all cosmetic changes first (these do not require user approval):
For each entry in SOURCE_CHANGES where classification == "cosmetic":
- Read the current ported target file:
Read: {PORT_OUTPUT_DIR}/{component_entry.target} - Apply whitespace and formatting changes to match the updated source
- Write the updated file using
Edittool - Add to
UPDATED_FILESwithupdate_type: "cosmetic"
Log: Applied {count} cosmetic updates automatically.
Step 2: Process Modified Components (Structural and Content)
For each entry in SOURCE_CHANGES where change_type == "modified" and classification is "structural" or "content":
2a: Load Conversion Context
-
Read the current source file:
Read: {source_change.file_path} -
Read the current ported target file:
Read: {PORT_OUTPUT_DIR}/{source_change.component_entry.target} -
Load the appropriate converter reference from
${CLAUDE_PLUGIN_ROOT}/references/:Source path contains Load converter /agents/agent-converter.md/hooks/hook-converter.md/references/reference-converter.md.mcp.jsonmcp-converter.mdSkills (default) adapters/{TARGET_PLATFORM}.md -
Also load the adapter file (
adapters/{TARGET_PLATFORM}.md) if not already loaded.
2b: Apply Structural Changes
For structural changes, re-run conversion on the changed sections:
- Identify changed sections by comparing the diff against the file structure
- For each changed section: extract updated content, apply converter mapping rules, replace the corresponding section in the ported target
- For frontmatter changes: parse updated frontmatter, apply adapter mappings, merge with existing ported frontmatter (preserve target-specific fields, update source-derived fields)
- For
allowed-tools/toolschanges: map new tools through adapter equivalents, remove dropped tools, flag tools with no target equivalent
2c: Apply Content Changes
For content changes, apply targeted text transformations:
- Identify specific text changes from the diff and locate them in the ported target
- Apply converter mapping rules to transform the new text
- Replace the old text, preserving any target-platform-specific modifications from the original port
2d: Check for New Incompatibilities
Load the incompatibility resolver:
Read: ${CLAUDE_PLUGIN_ROOT}/references/incompatibility-resolver.md
Check if any of the changes introduce new incompatibilities with the target platform:
- New tool references that have no target equivalent
- New composition patterns not supported by the target
- New agent configurations with no mapping
For each new incompatibility found, present it to the user:
AskUserQuestion:
questions:
- header: "New Incompatibility Detected"
question: |
The source change in {file_path} introduces a new incompatibility:
Feature: {feature_description}
Issue: {incompatibility_description}
Severity: {critical/functional/cosmetic}
How should this be handled?
options:
- label: "Apply workaround"
description: "{workaround_description}"
- label: "Add TODO placeholder"
description: "Insert a TODO comment for manual resolution"
- label: "Skip this change"
description: "Do not apply this specific change"
multiSelect: false
2e: Confirm and Apply
For each significant change (structural or content with incompatibilities), present a before/after preview:
AskUserQuestion:
questions:
- header: "Confirm Update: {file_name}"
question: |
Source change: {diff_summary}
Affected section: {section_name}
The ported file will be updated with the converted changes.
Apply this update?
options:
- label: "Apply"
description: "Update the ported file"
- label: "Skip"
description: "Leave the ported file unchanged for this change"
- label: "Show diff"
description: "View the detailed before/after comparison"
multiSelect: false
If "Show diff", display before/after and re-ask. If "Apply", write with Edit and add to UPDATED_FILES. If "Skip", add to SKIPPED_FILES.
Step 3: Handle New Components
For each entry in SOURCE_CHANGES where change_type == "added":
AskUserQuestion:
questions:
- header: "New Source Component"
question: |
A new component was detected: {file_path}
This file was added since the last port and requires a full conversion.
The update skill handles incremental changes; full conversions are best
handled by the port-plugin skill.
options:
- label: "Run /port-plugin for this component"
description: "Recommended: use the full porting workflow for new components"
- label: "Add to gap report"
description: "Note this as an unported component in the gap report"
- label: "Skip"
description: "Ignore this new component"
multiSelect: false
If "Run /port-plugin": add to NEW_COMPONENTS with action: "port" and inform user to run it after this update. If "Add to gap report": add with action: "gap".
Step 4: Handle Deleted Components
For each entry in SOURCE_CHANGES where change_type == "deleted":
AskUserQuestion:
questions:
- header: "Deleted Source Component"
question: |
Source component was deleted: {file_path}
Ported version exists at: {PORT_OUTPUT_DIR}/{target_path}
The source file no longer exists. What should we do with the ported version?
options:
- label: "Delete ported file"
description: "Remove the ported version since its source no longer exists"
- label: "Keep as orphaned"
description: "Keep the ported file but mark it as orphaned in the migration guide"
- label: "Skip"
description: "Take no action"
multiSelect: false
If "Delete": remove via Bash (rm {PORT_OUTPUT_DIR}/{target_path}) and add to DELETED_COMPONENTS. If "Keep as orphaned": prepend <!-- ORPHANED: Source file {source_path} was deleted on {date} --> and add to DELETED_COMPONENTS.
Phase 4: Apply Platform Changes
Goal: Update ported files to reflect changes in the target platform since the original port.
Skip this phase entirely if:
- User selected "Source changes only" in Phase 2
- User selected "Cancel" in Phase 2
PLATFORM_CHANGESis empty (no platform changes detected)
Step 1: Apply Breaking Changes
Process breaking changes first as they affect correctness.
1a: Stale Mappings
For each stale breaking change: identify affected ported files, locate stale mapping instances, and prepare replacements. Present each:
AskUserQuestion:
questions:
- header: "Stale Platform Mapping"
question: |
Platform mapping has changed for {TARGET_PLATFORM}:
Section: {adapter_section}
Old: {old_mapping}
New: {new_mapping}
Affected files ({affected_count}):
{list of affected ported files}
Apply the updated mapping?
options:
- label: "Apply to all affected files"
description: "Update all {affected_count} file(s) with the new mapping"
- label: "Apply selectively"
description: "Choose which files to update"
- label: "Skip"
description: "Keep the current mapping (may cause issues on the platform)"
multiSelect: false
If "Apply selectively", present each file individually. Apply updates via Edit and add to UPDATED_FILES with update_type: "platform_stale".
1b: Removed Features
For each removed breaking feature, identify affected files and present:
AskUserQuestion:
questions:
- header: "Removed Platform Feature"
question: |
{TARGET_PLATFORM} has removed or deprecated a feature used by ported components:
Feature: {feature_description}
{If alternative:}Alternative: {alternative}
{If no alternative:}No direct alternative available.
Affected files ({affected_count}):
{list of affected ported files}
How should this be handled?
options:
- label: "Apply alternative"
description: "Replace with: {alternative}"
- label: "Add TODO placeholder"
description: "Insert a TODO comment for manual resolution"
- label: "Remove feature usage"
description: "Remove references to this feature from ported files"
- label: "Keep as-is with warning"
description: "Leave unchanged but add a deprecation warning comment"
multiSelect: false
Apply the selected resolution to each affected file and add to UPDATED_FILES with update_type: "platform_removed".
Step 2: Apply Additive Changes
Present new platform features that could enhance ported components:
AskUserQuestion:
questions:
- header: "New Platform Features"
question: |
{TARGET_PLATFORM} has added new features since the last port.
Select which ones to apply to your ported components:
options:
- label: "{feature_description}"
description: "Benefit: {potential_benefit} -- affects {affected_count} component(s)"
multiSelect: true
For each selected feature: identify benefiting files, apply using adapter mapping rules, add to UPDATED_FILES with update_type: "platform_additive". If none selected, log: No additive platform changes applied.
Step 3: Update Adapter File
After applying platform changes, offer to update the adapter file:
AskUserQuestion:
questions:
- header: "Update Adapter File"
question: |
The adapter file for {TARGET_PLATFORM} may be stale based on the platform changes detected.
Would you like to update it?
options:
- label: "Update adapter"
description: "Apply validated platform changes to the adapter file"
- label: "Skip adapter update"
description: "Leave the adapter file unchanged (note: it may be stale)"
multiSelect: false
If "Update adapter": load validate-adapter (Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md), execute its update logic, and track the new version. If "Skip": log that adapter is stale and set ADAPTER_UPDATED = false.
Phase 5: Output & Refresh
Goal: Write all updated files, refresh the PORT-METADATA block, update the migration guide history, refresh the gap report, and present a final summary.
Step 1: Write Updated Files
For each file in UPDATED_FILES: if OUTPUT_DIR is specified, write to {OUTPUT_DIR}/{relative_target_path} (creating intermediate directories as needed); otherwise write in-place. Track results in WRITE_RESULTS (files_written and files_failed lists). If any writes fail, log the error and continue.
Step 2: Refresh PORT-METADATA
Get the current HEAD commit hash:
git rev-parse HEAD
Get today's date for the port_date field.
Build the updated PORT-METADATA block:
<!-- PORT-METADATA
source_commit: {current_HEAD_hash}
port_date: {today_date}
adapter_version: {new_adapter_version or PORT_METADATA.adapter_version if not updated}
target_platform: {PORT_METADATA.target_platform}
target_platform_version: {new_platform_version or PORT_METADATA.target_platform_version}
components:
{For each component in PORT_METADATA.components that was NOT deleted:}
- source: {component.source}
target: {component.target}
fidelity: {updated_fidelity_score or original if unchanged}
{For any NEW components that were fully ported:}
- source: {new_source_path}
target: {new_target_path}
fidelity: {new_fidelity_score}
PORT-METADATA -->
Fidelity score rules: Cosmetic/content changes keep original score. Structural changes and platform breaking changes trigger recalculation. Orphaned components are removed from the list.
Replace the old PORT-METADATA block in MIGRATION-GUIDE.md with the updated block using Edit tool.
Step 3: Append Update History
Add an update history entry to MIGRATION-GUIDE.md. If an ## Update History section already exists, append to it. If not, create it before the PORT-METADATA block.
## Update History
### {today_date} -- Incremental Update
- **Source changes**: {modified_count} files updated, {added_count} new, {deleted_count} deleted
- **Platform changes**: {stale_updated_count} mappings updated, {additive_applied_count} features added, {removed_handled_count} removals handled
- **Scope**: {source-only|platform-only|full}
- **Skipped**: {skipped_count} changes skipped by user
- **Components affected**: {affected_component_count}/{total_component_count}
If the Update History section already has entries, append the new entry at the top (most recent first).
Step 4: Refresh GAP-REPORT.md
Check if a GAP-REPORT.md exists in PORT_OUTPUT_DIR:
Glob: {PORT_OUTPUT_DIR}/GAP-REPORT.md
If exists: Read it, remove entries that were resolved by this update (mark as RESOLVED with date), add new entries for any new gaps (incompatibilities, removed features, skipped breaking changes), and write the updated file.
If does not exist: Create a new GAP-REPORT.md (following port-plugin format) only if there are new gaps. If no new gaps, do not create one.
Step 5: Final Summary
Present the update results via AskUserQuestion:
AskUserQuestion:
questions:
- header: "Update Complete"
question: |
Update summary for {TARGET_PLATFORM} port:
Files updated: {WRITE_RESULTS.files_written.length}
{For each file: - {path} ({update_type})}
New gaps introduced: {new_gap_count}
Gaps resolved: {resolved_gap_count}
Metadata refreshed: yes
Adapter updated: {yes/no}
Components:
- Updated: {updated_count}
- Skipped: {skipped_count}
- New (needs full port): {new_component_count}
- Deleted/orphaned: {deleted_count}
Next steps:
{If NEW_COMPONENTS with action "port":}
1. Run /port-plugin --target {TARGET_PLATFORM} for {new_count} new component(s)
{If SKIPPED_FILES.length > 0:}
2. Review {skipped_count} skipped change(s) for manual handling
{If ADAPTER_UPDATED == false and PLATFORM_CHANGES.length > 0:}
3. Consider updating the adapter file with /validate-adapter --target {TARGET_PLATFORM}
4. Test updated plugins on {TARGET_PLATFORM}
5. Review MIGRATION-GUIDE.md for full update history
options:
- label: "Done"
description: "Finish the update workflow"
- label: "View updated files"
description: "List all files that were modified"
- label: "Run another update"
description: "Check for additional changes"
multiSelect: false
If "View updated files": list all written files with paths and update types, then re-present options. If "Run another update": return to Phase 1 Step 3 (re-locate migration guide with refreshed metadata).
Error Handling
If any phase fails:
- Explain what went wrong
- Use
AskUserQuestionto ask how to proceed:AskUserQuestion: questions: - header: "Error Recovery" question: "{Description of what failed}. How would you like to proceed?" options: - label: "Retry this phase" description: "Attempt the failed phase again" - label: "Skip to next phase" description: "Continue without this phase's output" - label: "Cancel" description: "Exit the update workflow" multiSelect: false
Specific Error Scenarios
Git history unavailable: If git commands fail (not a git repo, corrupted history):
- Log:
WARNING: Git history is unavailable. Source change detection requires git history. - If
SOURCE_ONLYor full update: cannot detect source changes, offer to proceed with platform changes only or cancel - If
PLATFORM_ONLY: git is not needed, continue normally
Adapter file missing: If the adapter file for TARGET_PLATFORM does not exist:
- Log:
WARNING: No adapter file found for {TARGET_PLATFORM}. Platform change detection is limited. - Source changes can still be applied using generic conversion logic
- Platform changes cannot be fully evaluated without an adapter
Ported file write conflict: If a target file has been manually edited since the last port (detected by comparing file modification time against PORT_METADATA.port_date):
- Warn the user that the file appears to have manual edits
- Offer: "Overwrite", "Merge manually", or "Skip"
Reference Files
references/adapter-format.md-- Adapter file format specification (9 mapping sections)references/agent-converter.md-- Agent conversion logic (frontmatter mapping, body transformation, gap handling, fidelity scoring)references/hook-converter.md-- Hook conversion logic (event mapping, behavioral classification, workaround strategies)references/reference-converter.md-- Reference file conversion logic (discovery, path transformation, flattening)references/mcp-converter.md-- MCP config conversion logic (server mapping, transport types, tool reference renaming, platform support detection)references/incompatibility-resolver.md-- Incompatibility detection, interactive resolution, batch handling, decision trackingreferences/adapters/-- Directory for per-platform adapter files (one markdown file per target platform)
Validate Adapter
Validate an adapter file against live platform documentation to detect stale mappings, missing features, and outdated version information. Optionally apply updates in-place when the --update flag is provided.
CRITICAL: Complete ALL 4 phases. The workflow is not complete until Phase 4: Report & Apply 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.
- Summary and confirmation -> AskUserQuestion
- Report presentation -> AskUserQuestion
- Action selection -> AskUserQuestion
- Removal decisions -> AskUserQuestion
Text output should only be used for:
- Displaying progress updates between phases
- Presenting intermediate analysis results
- Explaining context or classification reasoning
If you need the user to make a choice or provide input, use AskUserQuestion.
NEVER do this (asking via text output):
Would you like to apply updates or export the report?
1. Apply updates
2. Export report
3. View details
ALWAYS do this (using AskUserQuestion tool):
AskUserQuestion:
questions:
- header: "Validation Complete"
question: "How would you like to proceed?"
options:
- label: "View detailed findings"
description: "Show full per-entry breakdown grouped by classification"
- label: "Apply updates"
description: "Update stale/missing entries in the adapter file"
- label: "Export report"
description: "Write validation report as a markdown file"
multiSelect: false
Composability
This skill can be invoked standalone via /validate-adapter or loaded as a sub-workflow by other skills (e.g., update-ported-plugin). When loaded as a sub-workflow:
- The caller may only need Phases 1-3 (the analysis) and not Phase 4 (the interactive report)
- If the caller has already set
SKIP_REPORT = truein context, stop after Phase 3 and return the validation report data structure to the caller - If no
SKIP_REPORTflag is present, execute all 4 phases (standalone behavior)
Plan Mode Behavior
CRITICAL: This skill performs an interactive validation workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:
- DO NOT create an implementation plan for how to build the validation feature
- DO NOT defer validation to an "execution phase"
- DO proceed with the full validation workflow immediately
- DO write updated adapter files or reports as normal
Phase Overview
Execute these phases in order, completing ALL of them:
- Load & Parse - Parse arguments, read adapter format spec and adapter file
- Platform Research - Spawn researcher agent to investigate current platform state
- Compare & Analyze - Compare adapter sections against research findings
- Report & Apply - Present findings and optionally update the adapter
Phase 1: Load & Parse
Goal: Parse arguments, load the adapter format specification, read the target adapter file, and extract its current state.
Step 1: Parse Arguments
Parse $ARGUMENTS for:
--target <platform>-- Target platform slug (default:opencode)--update-- Enable in-place update mode (default:false)
Set TARGET_PLATFORM from --target value (default: opencode).
Set UPDATE_MODE from --update flag (default: false).
Step 2: Load Adapter Format Specification
Read the adapter format reference to understand the expected 9-section structure:
Read: ${CLAUDE_PLUGIN_ROOT}/references/adapter-format.md
Record the 9 required/optional sections:
- Platform Metadata
- Directory Structure
- Tool Name Mappings
- Model Tier Mappings
- Frontmatter Translations
- Hook/Lifecycle Event Mappings
- Composition Mechanism
- Path Resolution
- Adapter Version
Step 3: Load Adapter File
Read the adapter file for the target platform:
Read: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md
Error handling -- adapter not found:
If the adapter file does not exist:
- Use Glob to list available adapters:
Glob: ${CLAUDE_PLUGIN_ROOT}/references/adapters/*.md - Present available options:
AskUserQuestion: questions: - header: "Adapter Not Found" question: "No adapter found for '${TARGET_PLATFORM}'. Which adapter would you like to validate?" options: - label: "{adapter-1}" description: "Adapter file: {adapter-1}.md" - label: "{adapter-2}" description: "Adapter file: {adapter-2}.md" multiSelect: false - If no adapters exist at all, inform the user and exit:
ERROR: No adapter files found in ${CLAUDE_PLUGIN_ROOT}/references/adapters/. Create an adapter first using /port-plugin or manually following the adapter format spec.
Step 4: Parse Adapter Sections
Parse all 9 sections from the adapter file by matching H2 (##) headers against the section names defined in the adapter format specification.
For each section found:
- Record section name, start line, end line, and raw content
- Count the number of table rows / list entries / code block entries (these are the "entries" for classification)
For each expected section NOT found:
- Record it as missing from the adapter
Step 5: Extract Metadata
From the Adapter Version section (Section 9), extract:
adapter_version-- semver version of this adapter filetarget_platform_version-- version of the platform the adapter was written forlast_updated-- ISO 8601 date of last review/update
If any of these fields are missing, record them as unknown.
Step 6: Present Summary and Confirm
AskUserQuestion:
questions:
- header: "Adapter Validation Summary"
question: |
Adapter loaded for validation:
| Field | Value |
|-------|-------|
| Platform | ${TARGET_PLATFORM} |
| Adapter Version | ${adapter_version} |
| Target Platform Version | ${target_platform_version} |
| Last Updated | ${last_updated} |
| Sections Found | ${found_count} / 9 |
| Update Mode | ${UPDATE_MODE ? 'Enabled' : 'Disabled'} |
Proceed with platform research?
options:
- label: "Proceed"
description: "Spawn researcher agent to investigate current platform state"
- label: "Cancel"
description: "Cancel validation"
multiSelect: false
If the user selects "Cancel", exit the workflow.
Phase 2: Platform Research
Goal: Spawn the researcher agent to gather current platform documentation and compare against the adapter.
Step 1: Spawn Researcher Agent
Spawn the researcher agent using the Task tool with subagent_type: "agent-alchemy-plugin-tools:researcher":
Task tool prompt:
"Research the current state of the plugin/extension system for: ${TARGET_PLATFORM}
You are validating an existing adapter file for this platform. The adapter was last updated on ${last_updated} and targets platform version ${target_platform_version}.
Focus your research on:
1. The current version of ${TARGET_PLATFORM} and any version changes since ${target_platform_version}
2. Plugin system changes, new features, or API modifications since the adapter was written
3. Deprecated or removed features that the adapter may still reference
4. New capabilities or configuration options not present in the adapter
The adapter file is located at: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md
Read the adapter file and perform your Phase 4: Adapter Comparison against your research findings. Pay special attention to:
- Tool name changes or new tools added to the platform
- Directory structure changes
- Configuration format changes
- Model/provider changes
- Hook/lifecycle system changes
- Composition mechanism changes
Return a structured platform profile with your Adapter Comparison section fully populated."
Retry logic: If the Task tool call fails (agent error, timeout, or empty response), retry once automatically. If the retry also fails, proceed to research failure handling in Step 3.
Step 2: Process Research Findings
When the researcher agent returns its platform profile:
- Store the full response as
RESEARCH_FINDINGS - Extract key data points:
research_platform_version-- current platform version found by researchdocumentation_quality-- excellent/good/fair/poor/noneoverall_confidence-- high/medium/lowsources_consulted-- count and list of sourcesstale_mappings-- list from the Adapter Comparison sectionmissing_mappings-- list from the Adapter Comparison section
- Display brief research summary as a progress update (text output, not AskUserQuestion):
Research complete: - Documentation quality: ${documentation_quality} - Overall confidence: ${overall_confidence} - Sources consulted: ${sources_count} (${official_count} official, ${community_count} community) - Platform version found: ${research_platform_version} (adapter targets: ${target_platform_version})
Step 3: Handle Research Failure
If the researcher agent fails or returns empty results:
- Inform the user of the failure
- Offer options:
AskUserQuestion: questions: - header: "Research Failed" question: "The researcher agent could not gather platform documentation. How would you like to proceed?" options: - label: "Retry research" description: "Spawn the researcher agent again" - label: "Manual validation" description: "Skip research; validate adapter structure only (no staleness detection)" - label: "Cancel" description: "Cancel the validation workflow" multiSelect: false - If "Retry research": go back to Step 1
- If "Manual validation": proceed to Phase 3 with empty research findings (all entries will be classified as "Uncertain")
- If "Cancel": exit the workflow
Phase 3: Compare & Analyze
Goal: Compare each adapter section against research findings and classify every entry.
Step 1: Section-by-Section Comparison
For each of the 9 adapter sections, compare the adapter content against the research findings.
Special handling for low-confidence research: If the researcher reported overall_confidence: low for an entire topic area, or if the Adapter Comparison section has no data for a given adapter section, mark the entire section as Uncertain rather than making unreliable per-entry classifications.
Step 2: Classify Entries
For each mapping/entry in each adapter section, classify it as one of:
| Classification | Meaning | Criteria |
|---|---|---|
| Current | Matches research findings | Adapter value aligns with what research found; no changes needed |
| Stale | Outdated information | Research has newer/different data for this entry; adapter needs updating |
| Missing | Not in adapter | Platform has features/capabilities that the adapter does not cover |
| Removed | No longer supported | Adapter references features the platform has deprecated or removed |
| Uncertain | Cannot determine | Research confidence is low; unable to reliably classify this entry |
Classification rules by section:
Platform Metadata:
- Compare
documentation_url,repository_url,plugin_docs_urlagainst research-discovered URLs - Check if
notesstill accurately describe the platform status - Flag URL changes as Stale; flag removed URLs as Removed
Directory Structure:
- Compare
plugin_root,skill_dir,agent_dir, etc. against research-discovered paths - Flag changed paths as Stale; flag new directories as Missing
Tool Name Mappings:
- Compare each tool mapping against research tool equivalents
- Flag renamed tools as Stale; flag new platform tools as Missing; flag removed tools as Removed
Model Tier Mappings:
- Compare model identifiers against research-discovered models
- Flag renamed or updated model identifiers as Stale; flag new tiers as Missing
Frontmatter Translations:
- Compare field mappings against research-discovered config format
- Flag changed field names as Stale; flag new fields as Missing
Hook/Lifecycle Event Mappings:
- Compare event mappings against research-discovered lifecycle events
- Flag new events as Missing; flag removed events as Removed
Composition Mechanism:
- Compare mechanism, syntax, and capabilities against research findings
- Flag changed behavior as Stale
Path Resolution:
- Compare resolution strategy and patterns against research findings
- Flag changed patterns as Stale
Adapter Version:
- Compare
target_platform_versionagainstresearch_platform_version - If versions differ, classify as Stale
- Check
last_updatedage -- if older than 6 months, add a note
Step 3: Build Validation Report
Construct the validation report with the following structure:
Per-section breakdown:
| Section | Total Entries | Current | Stale | Missing | Removed | Uncertain |
|---------|--------------|---------|-------|---------|---------|-----------|
| Platform Metadata | N | N | N | N | N | N |
| Directory Structure | N | N | N | N | N | N |
| Tool Name Mappings | N | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... | ... |
| **Totals** | **N** | **N** | **N** | **N** | **N** | **N** |
Overall health score:
Health Score = (Current entries / Total classified entries) * 100
Exclude Uncertain entries from the denominator (they neither help nor hurt the score). If all entries are Uncertain, report the health score as "N/A -- insufficient research data".
Stale entries detail list:
| Section | Entry | Current Value | Suggested Value | Source |
|---------|-------|--------------|-----------------|--------|
| {section} | {entry name} | {adapter value} | {research value} | {source URL or description} |
Missing entries detail list:
| Section | Feature | Description | Suggested Mapping |
|---------|---------|-------------|-------------------|
| {section} | {feature name} | {research description} | {suggested adapter value} |
Removed entries detail list:
| Section | Entry | Adapter Value | Evidence |
|---------|-------|--------------|----------|
| {section} | {entry name} | {current adapter value} | {evidence of removal from research} |
Store the complete report as VALIDATION_REPORT.
If SKIP_REPORT = true (sub-workflow mode), return VALIDATION_REPORT to the caller and stop here. Do not proceed to Phase 4.
Phase 4: Report & Apply
Goal: Present the validation report to the user and optionally apply updates.
Step 1: Present Validation Report
Determine the health indicator based on the health score:
- 90-100%: "Healthy"
- 70-89%: "Needs Attention"
- 50-69%: "Outdated"
- 0-49%: "Critically Outdated"
- N/A: "Insufficient Data"
Build the action options based on context:
- Always include "View detailed findings" and "Export report"
- Include "Apply updates" only if
UPDATE_MODE = trueAND there are stale/missing/removed entries - If
UPDATE_MODE = falseand there are findings, include a note that--updateflag enables in-place updates
AskUserQuestion:
questions:
- header: "Adapter Validation Report"
question: |
## ${TARGET_PLATFORM} Adapter -- ${health_indicator}
**Health Score: ${health_score}%**
| Metric | Count |
|--------|-------|
| Current | ${current_count} |
| Stale | ${stale_count} |
| Missing | ${missing_count} |
| Removed | ${removed_count} |
| Uncertain | ${uncertain_count} |
${stale_count + missing_count + removed_count > 0 ?
stale_count + " stale, " + missing_count + " missing, and " + removed_count + " removed entries found." :
"All entries are current. No updates needed."}
How would you like to proceed?
options:
- label: "View detailed findings"
description: "Show full per-entry breakdown grouped by classification"
- label: "Apply updates"
description: "Update the adapter file with research-backed corrections (requires --update flag)"
- label: "Export report"
description: "Write validation report to a markdown file"
multiSelect: false
Step 2: View Detailed Findings
If the user selects "View detailed findings":
-
Present the full per-entry breakdown grouped by classification:
Stale Entries (if any): Show the stale entries detail list with current value, suggested value, and source.
Missing Entries (if any): Show the missing entries detail list with feature name, description, and suggested mapping.
Removed Entries (if any): Show the removed entries detail list with entry name, current value, and evidence.
Uncertain Entries (if any): Show uncertain entries with a note explaining the low research confidence.
Current Entries (if any): Show a summary count per section (do not list every current entry individually).
-
After presenting details, re-present the action choice:
AskUserQuestion: questions: - header: "Next Steps" question: "What would you like to do with these findings?" options: - label: "Apply updates" description: "Update the adapter file with research-backed corrections" - label: "Export report" description: "Write validation report to a markdown file" - label: "Done" description: "Exit without taking action" multiSelect: false
Step 3: Apply Updates
If the user selects "Apply updates":
Guard check: If UPDATE_MODE = false, inform the user:
Update mode is not enabled. Re-run with the --update flag to apply changes:
/validate-adapter --target ${TARGET_PLATFORM} --update
Then return to the action choice prompt.
If UPDATE_MODE = true, proceed with updates:
-
Update stale entries: For each stale entry in the validation report:
- Read the current adapter file section containing the entry
- Use Edit to replace the old value with the research-suggested value
- Record the change:
{ section, entry, old_value, new_value }
-
Add missing entries: For each missing entry in the validation report:
- Determine the correct adapter section for the new entry
- Use Edit to add the new entry in the appropriate location within the section
- Follow the formatting conventions of the existing entries in that section
- Record the addition:
{ section, entry, new_value }
-
Handle removed entries: For each removed entry, ask the user individually:
AskUserQuestion: questions: - header: "Removed Feature: ${entry_name}" question: | The adapter references "${entry_name}" in the ${section} section, but research indicates this feature has been removed from ${TARGET_PLATFORM}. Evidence: ${evidence} What should be done with this entry? options: - label: "Remove entry" description: "Delete this entry from the adapter" - label: "Keep with deprecation note" description: "Keep the entry but add a deprecation note" multiSelect: false- If "Remove entry": use Edit to remove the entry from the adapter
- If "Keep with deprecation note": use Edit to append
[DEPRECATED]to the entry's notes column
-
Update metadata: In the Adapter Version section:
- Bump
adapter_versionpatch number (e.g.,1.0.0->1.0.1) - Update
last_updatedto today's date (ISO 8601 format) - Update
target_platform_versiontoresearch_platform_versionif it changed - Append to the
changelogfield:${new_version} (${today}): Validation-driven update — ${stale_count} stale entries updated, ${missing_count} missing entries added, ${removed_count} removed entries handled.
- Bump
-
Write updated adapter file:
Write: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md -
Display update summary:
Adapter updated successfully: - Stale entries updated: ${updated_stale_count} - Missing entries added: ${added_missing_count} - Removed entries handled: ${handled_removed_count} - New adapter version: ${new_version} - Target platform version: ${research_platform_version}
Step 4: Export Report
If the user selects "Export report":
-
Determine the output directory:
- If an
OUTPUT_DIRwas provided by a caller (sub-workflow mode), use it - Otherwise default to the project root
- If an
-
Write the validation report as markdown:
Write: ${OUTPUT_DIR}/adapter-validation-${TARGET_PLATFORM}.mdThe report file should include:
- Report header with platform name, date, and health score
- Per-section breakdown table
- Stale entries detail list
- Missing entries detail list
- Removed entries detail list
- Uncertain entries list with confidence notes
- Research sources consulted
- Recommendation (update adapter / adapter is current / insufficient data)
-
Inform the user of the export location:
Validation report exported to: ${OUTPUT_DIR}/adapter-validation-${TARGET_PLATFORM}.md
Error Handling
Missing Adapter File
Handled in Phase 1 Step 3. The user is offered available alternatives or informed that no adapters exist.
Researcher Agent Failure
Handled in Phase 2 Step 3. The user can retry, proceed with structural validation only, or cancel.
Empty Research Results
If the researcher returns a profile with all sections marked as "unknown" or confidence "low":
- Proceed to Phase 3 but classify all entries as Uncertain
- In Phase 4, note that the health score is "N/A" due to insufficient research data
- Recommend the user provide documentation URLs directly or try again later
Malformed Adapter File
If the adapter file cannot be parsed (missing H2 headers, unrecognized structure):
- Report which sections were found and which are missing or malformed
- Offer to validate only the parseable sections
- Note structural issues in the validation report
Agent Coordination
The researcher agent is spawned via Task tool with subagent_type: "agent-alchemy-plugin-tools:researcher". The researcher uses Sonnet model and has access to WebSearch, WebFetch, Read, Glob, Grep, and Context7 tools.
Key coordination points:
- Pass the adapter file path to the researcher so it can perform its Phase 4: Adapter Comparison
- The researcher returns a structured platform profile with an Adapter Comparison section
- This skill consumes the Adapter Comparison data to drive the classification in Phase 3
- If the researcher fails, this skill degrades gracefully to structural validation only
Agents 2
Port Converter Agent
You are a plugin component converter. You convert a single Claude Code plugin component (skill, agent, hooks, reference, or MCP config) to a target platform format.
You are spawned by the port-plugin skill as part of a wave-based conversion team. Each converter agent runs in an isolated context with only the knowledge it needs.
Context
You receive via your spawn prompt:
- Component details: type, group, name, source path
- Session directory: path to
.claude/sessions/__port_live__/ - Target platform: the platform being ported to
- Converter reference to load: which type-specific reference file to read (if any)
Process Overview
Execute these steps in order:
- Load session files — read shared knowledge from the session directory
- Read source component — load the original component file
- Build mappings — parse conversion knowledge into lookup tables
- Convert the component — route by type, transform content
- Detect incompatibilities — identify and classify gaps
- Score fidelity — calculate the conversion quality score
- Write result file — output structured result to the session results directory
Step 1: Load Session Files
Read the following files from the session directory:
Read: {session_dir}/conversion_knowledge.md
Read: {session_dir}/resolution_cache.md
Read: {session_dir}/dependency_graph.md
Parse each file according to the formats defined in the session format reference.
Error handling: If any session file is missing or unreadable, log a warning and continue with available data. conversion_knowledge.md is required — if it cannot be read, report failure in the result file and exit.
Step 2: Read Source Component
Read the component source file at the path provided in the spawn prompt. Split the file into:
- Frontmatter: YAML block between
---delimiters (if present) - Body: Everything after the closing
---
If the file cannot be read, write a minimal result file with Status = error and exit.
Step 3: Build Mappings
Parse conversion_knowledge.md into structured lookup tables. For each mapping section, extract rows into key-value pairs:
MAPPINGS.tool_names:{ claude_tool -> { target, notes, confidence } }MAPPINGS.model_tiers:{ claude_tier -> { target, notes, confidence } }MAPPINGS.frontmatter_skill:{ claude_field -> { target_field, notes, confidence } }MAPPINGS.frontmatter_agent:{ claude_field -> { target_field, notes, confidence } }MAPPINGS.hook_events:{ claude_event -> { target_event, notes, confidence } }MAPPINGS.directory_structure:{ plugin_root, skill_dir, agent_dir, ... }MAPPINGS.composition:{ mechanism, syntax, supports_cross_plugin, ... }MAPPINGS.path_resolution:{ root_variable, same_plugin_pattern, cross_plugin_pattern, ... }
Also parse resolution_cache.md into:
RESOLUTION_CACHE:{ group_key -> { decision_type, workaround_applied, first_component, apply_globally } }
Step 4: Convert the Component
Route to the appropriate conversion procedure based on the component type.
Skills (type: "skill")
Skill conversion is the most common path. Apply these sub-steps:
4a: Transform Frontmatter
For each frontmatter field, look up its target equivalent in MAPPINGS.frontmatter_skill:
- Direct mapping (target is a string): Rename the field to the target name, keep the value
- Null mapping: Field has no equivalent. Record as omitted in decisions. Do not include in output.
- Embedded mapping (
embedded:{location}): Information must be placed elsewhere (filename, body). Record as relocated. Apply during body transformation.
For the allowed-tools list:
- Look up each tool in
MAPPINGS.tool_names - Non-null target: replace with target name
- Null target: remove from list, add to gaps with severity based on body usage (functional if referenced in body, cosmetic if only in tool list)
partial:{name}: use target name, record as partial mappingcomposite:{tool1}+{tool2}: expand into component tools, record as composite
For the model field (if present):
- Look up in
MAPPINGS.model_tiers - Non-null: replace value. Null: omit, record as gap.
4b: Transform Tool References in Body
Scan the body for references to Claude Code tools. Only replace when context indicates a tool reference (preceded by "Use ", "Run ", "Call ", "the ", or in backticks/code blocks).
For each tool reference:
- Direct mapping exists: replace the tool name
- Null: insert TODO comment:
<!-- TODO: {tool_name} has no equivalent on {TARGET_PLATFORM}. {notes} --> partial:{name}: replace and add inline note about limitation
4b-2: Transform Task Tool Invocation Patterns
Scan the body for Task tool invocation patterns that reference custom agents:
Detection patterns:
subagent_type: "{plugin}:{agent-name}"(e.g.,subagent_type: "agent-alchemy-core-tools:code-explorer")subagent_type: "{agent-name}"(e.g.,subagent_type: "code-explorer")subagent_typereferences in YAML code blocks and prose
Transformation rules:
- Check the adapter's Tool Name Mappings for the Task tool entry. If the notes mention a
commandparameter for custom agent spawning:- Replace
subagent_type: "{plugin}:{agent-name}"withcommand: "{agent-name}"(strip the plugin prefix) - Replace
subagent_type: "{agent-name}"withcommand: "{agent-name}"(keep as-is if already just the agent name) - Keep built-in subagent types (
build,plan) assubagent_type— do NOT convert these tocommand
- Replace
- If the adapter's Task notes do NOT mention a
commandparameter, leavesubagent_typepatterns unchanged - Record each transformation in Decisions: "Converted subagent_type '{original}' to command '{agent-name}' for custom agent spawning"
4c: Transform Composition Patterns
Scan for skill composition references:
Same-plugin loading: Read ${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md
Cross-plugin loading: Read ${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md
Reference loading: Read ${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{file}
Transform based on MAPPINGS.composition.mechanism:
importorinclude: Replace with target platform's composition syntax, adjust path usingMAPPINGS.path_resolutioninline: Mark insertion point with<!-- INLINE: {path} -->. Record as flattened.reference: Replace with name/ID-based reference using target's syntaxnone: All referenced content must be inlined. Follow same procedure asinlinebut add gap entry.
For cross-plugin references, check MAPPINGS.composition.supports_cross_plugin:
true: Convert using target's cross-plugin path patternfalse: Mark as unresolved incompatibility (unsupported composition, severity: critical or functional based on whether the composition is essential)
4d: Transform Path References
For remaining ${CLAUDE_PLUGIN_ROOT} occurrences not handled by composition:
- If
root_variableis non-null: replace with target variable - If
root_variableis null: convert to relative path or target'ssame_plugin_pattern - For
/../{group}/cross-plugin segments: applycross_plugin_patternor add TODO
4e: Transform AskUserQuestion Patterns
Scan for AskUserQuestion usage (YAML code blocks and prose):
- Direct equivalent exists in
MAPPINGS.tool_names: Replace references and adjust syntax - Null (no equivalent): Convert structured questions to prose instructions:
- multiSelect → bulleted option list with "List your selections"
- single-select → numbered option list with "Choose one"
- confirmation → yes/no instruction
Record as
interaction_downgraded. Add gap entry.
4f: Assemble Converted Skill
- Reconstruct frontmatter with mapped field names (if target uses frontmatter)
- Or construct metadata in target's format
- Append transformed body
- Apply target file extension from
MAPPINGS.directory_structure.file_extension - Apply naming convention for output filename
- Build output path using
skill_file_patternif defined:- If
MAPPINGS.directory_structure.skill_file_patternexists (e.g.,{name}/SKILL.md):- Replace
{name}with the skill name (applying naming convention) - Build output path:
{skill_dir}/{expanded_pattern}(e.g.,skills/deep-analysis/SKILL.md)
- Replace
- If no
skill_file_patternis defined:- Build output path:
{skill_dir}/{converted_filename}(flat file, e.g.,skills/deep-analysis.md)
- Build output path:
- If
Agents (type: "agent")
Read the agent converter reference and follow its procedures:
Read: ${CLAUDE_PLUGIN_ROOT}/references/agent-converter.md
The reference covers frontmatter parsing, model/tool transformation, body transformation (reuse skill steps 4b-4d above for body content), gap handling, and assembly.
Hooks (type: "hooks")
Read the hook converter reference and follow its procedures:
Read: ${CLAUDE_PLUGIN_ROOT}/references/hook-converter.md
The reference covers JSON parsing, event type mapping, matcher transformation, command/script path conversion, and assembly.
Reference Files (type: "reference")
Read the reference file converter reference and follow its procedures:
Read: ${CLAUDE_PLUGIN_ROOT}/references/reference-converter.md
The reference covers discovery, path transformation, content transformation, and output strategy (standalone vs. inline).
MCP Configs (type: "mcp")
Read the MCP converter reference and follow its procedures:
Read: ${CLAUDE_PLUGIN_ROOT}/references/mcp-converter.md
The reference covers server config parsing, transport mapping, path resolution, tool reference renaming, and gap handling.
Step 5: Detect and Handle Incompatibilities
Throughout Step 4, when a mapping returns null and the feature is non-trivial, create an incompatibility entry.
Classification
Assign each incompatibility to one of 5 categories:
- Unmapped tool — tool maps to
nullinMAPPINGS.tool_names - Unmapped frontmatter field — field maps to
nullin frontmatter mappings - Unsupported composition — composition mechanism is
noneor cross-plugin not supported - Unsupported hook event — event maps to
nullinMAPPINGS.hook_events - General feature gap — both adapter and research report no equivalent
Severity Assignment
Apply this heuristic:
For unmapped tools:
- Count occurrences in body text
- Check if tool appears in
allowed-tools - Occurrences > 3 AND in allowed-tools: critical
- Occurrences > 0 AND in allowed-tools: functional
- Occurrences > 0 but NOT in allowed-tools: functional
- Only in allowed-tools with 0 body references: cosmetic
For other categories, assess by impact on component's core function.
Group Key Assignment
Assign group_key for batch grouping:
- Unmapped tools:
unmapped_tool:{tool_name} - Unmapped fields:
unmapped_field:{field_name} - Composition gaps:
unsupported_composition:{mechanism_type} - Hook events:
unsupported_hook:{event_type} - General gaps:
general_gap:{feature_name}
Workaround Suggestion
Build suggested workarounds using source priority:
- Adapter notes (highest): Use notes from conversion knowledge mapping tables
- Research findings (second): Alternative approaches documented for target platform
- Pattern-based inference (fallback): Default workarounds by category:
| Category | Default Workaround | Confidence |
|---|---|---|
| Unmapped tool (body) | Replace with prose instructions | low |
| Unmapped tool (allowed-tools only) | Remove from tool list, document loss | medium |
| Unmapped field (metadata) | Preserve as comment | medium |
| Unmapped field (behavioral) | Inline behavior into body | low |
| Unsupported composition (same-plugin) | Inline referenced content | medium |
| Unsupported composition (cross-plugin) | Inline or manual copy instruction | low |
| Unsupported hook event | Document purpose, suggest alternatives | low |
| General gap (inter-agent) | Remove, restructure as single-agent | low |
| General gap (task management) | Remove, document limitation | low |
| General gap (MCP) | Document servers, suggest manual config | medium |
Resolution Protocol
Cosmetic auto-resolution: If severity is "cosmetic" and a workaround exists with confidence "high" or "medium":
- Apply the workaround directly in the converted content
- Record in the result file Decisions table with
resolution_mode: "auto" - Do NOT add to Unresolved Incompatibilities
Cache lookup: For non-cosmetic incompatibilities, check RESOLUTION_CACHE:
- If
group_keyfound withapply_globally = true: apply the cached decision, record withresolution_mode: "cached" - If found with
apply_globally = falseOR not found: insert inline marker and add to Unresolved Incompatibilities
Clean output rule: Auto-resolved and cached-resolved items must NOT leave resolution_mode, group_key, or internal metadata in the converted content. These fields are internal tracking data:
- Workaround text is applied directly to the converted content without wrapping metadata
- TODO comments use clean format:
<!-- TODO: {description} -->(noresolution_modeorgroup_keyannotations) - All detailed metadata (resolution_mode, group_key, severity, workaround details) belongs exclusively in the result file's Decisions and Gaps tables, NOT in the converted output
Inline marker format:
<!-- UNRESOLVED: {group_key} | {severity} | {feature_name} | {workaround_description_or_none} -->
Insert markers at the relevant location in the converted content:
- For frontmatter fields: above where the field would have been
- For body text: replacing the original reference
- For composition patterns: at the original
Readdirective location - For hook entries: in the converted config or as a separate block
Step 6: Fidelity Scoring
After conversion is complete, calculate the component's fidelity score.
Feature Tracking
During conversion, classify every discrete feature into exactly one category:
direct_count— features with direct 1:1 mapping (no loss)workaround_count— features mapped viapartial:,composite:, workarounds,interaction_downgraded,flattened,relocatedtodo_count— features converted to TODO placeholdersomitted_count— features removed entirely
A "discrete feature" is any individually mappable element:
- Each frontmatter field
- Each entry in
allowed-tools - Each composition reference
- Each path reference (
${CLAUDE_PLUGIN_ROOT}occurrence) - Each interaction pattern (AskUserQuestion invocation)
- Each hook event entry
- Each MCP server configuration
Score Calculation
total_features = direct_count + workaround_count + todo_count + omitted_count
fidelity_score = ((direct * 1.0) + (workaround * 0.7) + (todo * 0.2) + (omitted * 0.0)) / total_features * 100
Round to nearest integer.
Edge case — No mappable features: If total_features == 0, set fidelity_score = 0.
Color Bands
| Score Range | Band | Label | Status |
|---|---|---|---|
| 80-100% | green | High fidelity | full |
| 50-79% | yellow | Moderate fidelity | partial |
| 0-49% | red | Low fidelity | limited |
Step 7: Write Result File
Write the structured result to {session_dir}/results/result-{component-id}.md using the format specified in the session format reference.
The result file must contain all sections:
- Metadata — component identification and scores
- Converted Content — full converted file content (wrapped in fenced code block)
- Fidelity Report — scoring breakdown
- Decisions — all conversion decisions with rationale
- Gaps — all identified gaps with severity
- Unresolved Incompatibilities — items for orchestrator to resolve with user
Component ID format: {type}-{group}-{name} (e.g., skill-core-tools-deep-analysis)
Config Fragments
If the adapter defines a Config File Format section (with config_file), collect JSON fragments produced during conversion and include them in the result file. These fragments are aggregated by the orchestrator in Phase 6 to generate the unified config file.
Config fragments may include:
- Agent model configs:
{ "agent": { "{agent-name}": { "model": "{target-model-id}" } } }— produced when converting agents withmodelfield - MCP server configs:
{ "mcp": { "{server-name}": { ... } } }— produced when converting MCP configs - Reference instruction entries:
{ "instruction": ["{path-to-reference}"] }— produced when using the instruction-array strategy for references - Permission entries:
{ "permission": { "{tool}": "allow" } }— produced when converting auto-approve hooks to permission config
Include the fragments in the result file under a ## Config Fragments section:
## Config Fragments
```json
{
"agent": {
"code-explorer": {
"model": "anthropic/claude-sonnet-4-6"
}
}
}
After writing the result file, your work is complete. The orchestrator will read the result, resolve any unresolved incompatibilities with the user, and proceed to the next wave.
---
## Important Notes
- You work autonomously without user interaction. All incompatibilities that require user decisions are deferred to the orchestrator via inline markers and the Unresolved Incompatibilities table.
- Load type-specific converter references on demand — only read the reference file relevant to your component type.
- The `conversion_knowledge.md` file is your primary source of truth for mappings. Trust its content.
- Write the result file even if conversion partially fails. A result with errors and gaps is more useful than no result.
- Do not modify session files other than writing your own result file. The orchestrator manages `resolution_cache.md` and other shared state.
Platform Research Agent
You are a platform research specialist for the plugin tools workflow. Your job is to thoroughly investigate a target AI coding platform's plugin/extension system and produce a structured platform profile that the conversion engine uses to map Claude Code plugin constructs to the target format.
Context
You are spawned by the porter skill before conversion begins. You receive:
- Target platform name (e.g., "OpenCode")
- Existing adapter file path (optional) -- a markdown adapter file with current mappings to compare against
Your findings feed directly into the conversion engine. Accuracy and completeness determine conversion quality.
Research Process
Phase 1: Official Documentation
Fetch the target platform's official plugin/extension documentation.
-
Use Context7 first for well-known platforms:
1. mcp__context7__resolve-library-id to find the platform's library ID 2. mcp__context7__query-docs with queries about plugin system, extension API, configuration format -
If Context7 does not have the platform, fall back to:
- WebSearch for "{platform} plugin documentation" or "{platform} extension system"
- WebFetch the official documentation URLs found
-
Extract from official docs:
- Plugin directory structure and file naming conventions
- Configuration file format (YAML, JSON, TOML, etc.)
- Available tools/capabilities and their names
- Model configuration options
- Lifecycle hooks or event system
- How plugins compose or reference each other
- Path resolution mechanisms
Phase 2: Community Examples
Search for real-world plugins and community resources.
-
WebSearch for:
- "{platform} plugin examples github"
- "{platform} custom tools tutorial"
- "{platform} extension development guide"
- "building plugins for {platform}"
-
WebFetch 2-3 promising GitHub repositories or blog posts
-
Extract from community examples:
- Common patterns and conventions not in official docs
- Practical file structures from real plugins
- Workarounds for platform limitations
- Community-established best practices
Phase 3: Existing Plugin Analysis
If the target platform has a plugin ecosystem, analyze existing plugins.
-
WebSearch for:
- "{platform} plugin marketplace" or "{platform} plugin registry"
- "popular {platform} plugins"
-
Identify 2-3 well-structured plugins and analyze:
- Directory layout
- Configuration patterns
- Tool definitions
- How they handle composition (if applicable)
Phase 4: Adapter Comparison
If an existing adapter file path was provided:
- Read the adapter file
- Compare each mapping against your research findings
- Flag any mappings that appear outdated or incorrect
- Identify new platform features not covered by the adapter
- Note the adapter version and whether it matches the current platform version
Handling Research Challenges
Minimal or No Documentation
If the platform has limited documentation:
- Report which documentation sources were attempted and what was found
- Mark all findings derived from limited sources with confidence: low
- Increase reliance on community examples and existing plugins
- Explicitly state: "Official documentation is sparse. Findings are based primarily on community sources and may be incomplete."
- Return partial findings rather than failing -- any information helps the conversion
Conflicting Information Between Sources
When sources disagree:
- Present both findings clearly, noting the source of each
- Indicate which source is more authoritative (official docs > community > blog posts)
- Mark the conflicting finding with confidence: medium and add a
conflictflag - Let the conversion engine or user decide which to follow
Research Timeout or Failure
If web search or fetch operations fail:
- Report which operations failed and why
- Return whatever findings were gathered before the failure
- Mark incomplete sections with confidence: low and note: "Research incomplete due to {reason}"
- Do not block the conversion -- partial findings are better than none
No Search Results
If web searches return no relevant results:
- Try alternative search terms (synonyms, related terms, the platform's parent project name)
- If still no results, report: "No documentation found for {platform}'s plugin system. The platform may not have a public plugin architecture, or it may use different terminology."
- Suggest the user provide documentation URLs directly
- Return an empty platform profile with all sections marked as "unknown"
Output Format
Structure your findings as a platform profile:
## Platform Profile: {Platform Name}
### Research Summary
- **Documentation quality**: {excellent/good/fair/poor/none}
- **Sources consulted**: {count} official, {count} community, {count} existing plugins
- **Overall confidence**: {high/medium/low}
- **Research date**: {date}
### Plugin System Overview
{2-3 paragraph description of how the platform's plugin system works}
### Directory Structure
{expected directory layout for a plugin}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}
### File Format
- **Config format**: {YAML/JSON/TOML/etc.}
- **Prompt format**: {markdown/plain text/etc.}
- **Metadata mechanism**: {frontmatter/separate config file/etc.}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}
### Tool Equivalents
| Claude Code Tool | {Platform} Equivalent | Notes | Confidence |
|------------------|----------------------|-------|------------|
| Read | {equivalent or "none"} | {notes} | {high/med/low} |
| Write | {equivalent or "none"} | {notes} | {high/med/low} |
| Edit | {equivalent or "none"} | {notes} | {high/med/low} |
| Glob | {equivalent or "none"} | {notes} | {high/med/low} |
| Grep | {equivalent or "none"} | {notes} | {high/med/low} |
| Bash | {equivalent or "none"} | {notes} | {high/med/low} |
| Task | {equivalent or "none"} | {notes} | {high/med/low} |
| WebSearch | {equivalent or "none"} | {notes} | {high/med/low} |
| WebFetch | {equivalent or "none"} | {notes} | {high/med/low} |
| AskUserQuestion | {equivalent or "none"} | {notes} | {high/med/low} |
### Model Tier Mappings
| Claude Tier | {Platform} Equivalent | Notes | Confidence |
|-------------|----------------------|-------|------------|
| opus | {equivalent} | {notes} | {high/med/low} |
| sonnet | {equivalent} | {notes} | {high/med/low} |
| haiku | {equivalent} | {notes} | {high/med/low} |
### Composition Patterns
- **Skill loading**: {how the platform handles loading/composing prompts}
- **Agent spawning**: {how subagents or subtasks work, if supported}
- **Reference files**: {how supplementary files are included}
- **Path resolution**: {equivalent of ${CLAUDE_PLUGIN_ROOT}}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}
### Lifecycle Hooks
- **Supported events**: {list of hook/event types}
- **Hook format**: {how hooks are defined}
- **Equivalent of PreToolUse/PostToolUse/Stop**: {mappings or "not supported"}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}
### Known Limitations
- {Limitation 1}: {impact on conversion}
- {Limitation 2}: {impact on conversion}
- **Confidence**: {high/medium/low}
### Adapter Comparison (if adapter file was provided)
- **Adapter version**: {version from adapter file}
- **Current platform version**: {version found in research}
- **Stale mappings**: {list of mappings that appear outdated}
- **Missing mappings**: {platform features not in adapter}
- **Recommendation**: {update adapter / adapter is current}
### Sources
- [{Source title}]({URL}) -- {what was found here}
- [{Source title}]({URL}) -- {what was found here}
Quality Standards
- Accuracy over completeness: Only report information you can verify from sources. Mark uncertain findings with low confidence rather than guessing.
- Attribution: Every finding should trace back to a source. Include URLs.
- Currency: Note the date of sources when available. Flag anything older than 6 months.
- Structured output: Always return the full platform profile template, even if sections are empty. Empty sections signal gaps to the conversion engine.
- No fabrication: If you cannot find information about a platform feature, report it as "unknown" rather than inferring from other platforms.
Important Notes
- Research is always fresh per session -- do not assume cached or prior knowledge about the platform
- Prioritize official documentation over community sources
- The platform profile is consumed by the conversion engine, so consistency in format is critical
- Report partial findings rather than failing entirely -- any verified information helps
- Do not include copyrighted content verbatim; summarize and cite
Hooks 1
Sponsors
Details
- Marketplace
- sequenzia/agent-alchemy
- Source
- claude/plugin-tools
- Category
- Community
- License
- MIT