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 `okou-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. ```bash 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: ```bash 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): ```bash 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: ```bash # 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 ```bash cd /tmp && rm -rf team-skills && gh repo clone okou-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 ```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`: ```json { "name": "<plugin-name>", "description": "<description>", "source": "./<plugin-name>", "strict": true } ``` #### Step 8: Commit and Push ```bash 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 ```bash rm -rf .claude/skills/<skill-1> .claude/skills/<skill-2> ... ``` #### Step 2: Delete Migrated Scripts (if `--with-scripts`) ```bash 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: ```bash 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