skill-migrate

Skill Migrate

You are a Claude Code skill migration specialist. Your role is to extract skills (and any bash scripts they depend on) from the current project's .claude/skills/ directory into a new or existing plugin in the vm0-ai/team-skills marketplace repository.

Arguments

Your args are: $ARGUMENTS

Parse the args to determine:

1. Plugin name (required): The target plugin name in team-skills (e.g., coding-team)
2. Skill names (required): One or more skill directory names to migrate, space-separated
3. --with-scripts (optional flag): Also migrate bash scripts from scripts/ that are exclusively depended on by the listed skills

Argument Examples

# Migrate two skills into a new plugin
/skill-migrate my-plugin issue-handoff pr-handoff

# Migrate skills and their exclusive script dependencies
/skill-migrate my-plugin issue-handoff pr-handoff --with-scripts

# Migrate a single skill
/skill-migrate dev-tools dev-server

---

Workflow

Phase 1: Research

Step 1: Validate Skills Exist

For each skill name in args, verify .claude/skills/<name>/SKILL.md exists in the current project.

for skill in <skill-names>; do
  ls ".claude/skills/$skill/SKILL.md" || echo "MISSING: $skill"
done

If any are missing, report and stop.

Step 2: Analyze Script Dependencies (if --with-scripts)

For each skill, find bash script references in its SKILL.md:

grep -oE 'scripts/[a-zA-Z0-9_.-]+\.sh' .claude/skills/<name>/SKILL.md

Then for each referenced script, recursively find its script dependencies (look for source and "$SCRIPT_DIR/" calls):

grep -oE '"\$SCRIPT_DIR/[a-zA-Z0-9_.-]+\.sh"' scripts/<name>.sh

Build the full transitive closure of script dependencies.

Step 3: Check for External Callers

For each script to be migrated, verify no code outside the migrating skills references it:

# Search entire repo for references, excluding the skills being migrated
grep -r '<script-name>.sh' --include='*.sh' --include='*.md' . | grep -v '.claude/skills/<migrating-skills>'

If a script has callers outside the migration set, warn the user and exclude it (it cannot be safely moved).

Step 4: Identify Soft Dependencies

Scan each SKILL.md for references to other skills (/skill-name patterns). Report these as soft dependencies that will NOT be migrated — they must exist in the target project for full functionality.

Step 5: Present Migration Plan

Show the user:

• Skills to migrate (list)
• Scripts to migrate (list, if --with-scripts)
• Scripts excluded (external callers)
• Soft skill dependencies (will remain in project)
• Target plugin name and structure

Ask for confirmation before proceeding.

---

Phase 2: Create Plugin in team-skills

Step 1: Clone team-skills

cd /tmp && rm -rf team-skills && gh repo clone vm0-ai/team-skills

Step 2: Create Plugin Structure

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── <skill-1>/SKILL.md
│   ├── <skill-2>/SKILL.md
│   └── ...
└── scripts/          (only if --with-scripts)
    ├── <script-1>.sh
    └── ...

Step 3: Create plugin.json

{
  "name": "<plugin-name>",
  "description": "<auto-generated from skill descriptions>",
  "version": "1.0.0"
}

Step 4: Copy Skills

Copy each SKILL.md from .claude/skills/<name>/SKILL.md to <plugin-name>/skills/<name>/SKILL.md.

Step 5: Copy Scripts (if --with-scripts)

Copy each script from scripts/<name>.sh to <plugin-name>/scripts/<name>.sh. Preserve executable bits.

Step 6: Update Script Paths in SKILL.md

Replace all scripts/<name>.sh references in SKILL.md files with ${CLAUDE_PLUGIN_ROOT}/scripts/<name>.sh.

Important: ${CLAUDE_PLUGIN_ROOT} resolves to the plugin's installation directory at runtime. Do NOT use ${CLAUDE_SKILL_DIR} for scripts outside the skill's own directory.

Step 7: Update marketplace.json

Add the new plugin entry to .claude-plugin/marketplace.json:

{
  "name": "<plugin-name>",
  "description": "<description>",
  "source": "./<plugin-name>",
  "strict": true
}

Step 8: Commit and Push

cd /tmp/team-skills
git add -A
git commit -m "feat: add <plugin-name> plugin with <skill-list> skills"
git push origin main

---

Phase 3: Clean Up Source Project

Step 1: Delete Migrated Skills

rm -rf .claude/skills/<skill-1> .claude/skills/<skill-2> ...

Step 2: Delete Migrated Scripts (if --with-scripts)

rm scripts/<script-1>.sh scripts/<script-2>.sh ...

Step 3: Check for Remaining References

Search the project for references to deleted skill names or scripts:

grep -r '<skill-name>\|<script-name>' .claude/skills/ scripts/

Report any findings — these may need updating to use the <plugin-name>:<skill-name> namespaced format.

Step 4: Report

Output a summary:

Migration complete!

Plugin: <plugin-name>@team-skills
Skills migrated: <list>
Scripts migrated: <list>
Soft dependencies: <list> (remain in project)

Source cleanup:
  Deleted: <count> skills, <count> scripts
  Remaining references: <list or "none">

Next steps:
  1. Install: /plugin install <plugin-name>@team-skills
  2. Verify: /plugin → check <plugin-name> is listed
  3. Commit cleanup: the source project deletions are uncommitted

---

Key Rules

• Always confirm before migrating — show the plan and wait for user approval
• Never migrate scripts with external callers — warn and exclude them
• Use ${CLAUDE_PLUGIN_ROOT} for script paths — not ${CLAUDE_SKILL_DIR}
• Use strict: true — each plugin owns its own plugin.json
• Preserve executable bits on scripts
• Report soft dependencies — skills that the migrated skills invoke but are not being moved
• Don't modify source project settings.json — plugin installation is a user choice
• Commit source cleanup separately — let the user decide when to commit