# Skill Migrate

> Migrate skills (and their script dependencies) from the current project into a plugin in the team-skills marketplace repo.

- Skill: `vm0-ai/skill-migrate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vm0-ai/skill-migrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vm0-ai/skill-migrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vm0-ai (https://skillmd.com/u/vm0-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vm0-ai/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.

```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 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

```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