---
name: skill-migrator
description: This skill should be used when the user asks to "migrate skills from a directory", "import tools to opencode", "move llm tools", "copy skills from a path", "transfer skills to opencode", "install skills from a directory", or migrate LLM tools between directories
license: MIT
compatibility: opencode
metadata:
  category: tools
  version: "1.0.0"
---

# Skill Migrator

Migrate LLM tools and skills from any directory to OpenCode's skills directory. Supports both global (`~/.config/opencode/skills/`) and local project (`.opencode/skills/`) installations.

## Overview

This skill provides a streamlined way to import skills from external sources or backup locations into OpenCode. It handles skill discovery, conflict resolution, and installation to the appropriate location.

## Common Use Cases

### Migrate Skills from a Directory

Import all skills from a source directory:

```bash
scripts/migrate.sh /path/to/source/skills
```

The script will:
1. Recursively discover all skills (directories containing `SKILL.md`)
2. List found skills and ask which to migrate
3. Handle conflicts interactively (overwrite/skip/backup)
4. Install to global skills directory by default

### Non-Interactive Mode (Automation-Friendly)

For use with opencode or automated workflows, use the non-interactive flags:

```bash
# Migrate all skills without prompts
scripts/migrate.sh /path/to/source/skills --all --yes

# Migrate all, skip existing skills (no overwrite)
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy skip

# Migrate all, overwrite existing skills
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy overwrite

# Migrate all, backup existing before overwriting
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy backup
```

### Install to Local Project

Migrate skills to the current project's local skills directory:

```bash
# Interactive mode
scripts/migrate.sh /path/to/source/skills --local

# Non-interactive mode
scripts/migrate.sh /path/to/source/skills --local --all --yes
```

### Dry Run (Preview)

See what would be migrated without making changes:

```bash
# Preview only
scripts/migrate.sh /path/to/source/skills --dry-run

# Preview with non-interactive flags
scripts/migrate.sh /path/to/source/skills --all --dry-run
```

### Migrate Specific Skills

After discovery, the script presents an interactive menu to select which skills to migrate. Choose specific skills or migrate all discovered skills.

## Migration Process

### Step 1: Discovery

The script searches the source directory recursively for skills:
- Looks for directories containing `SKILL.md`
- Lists all discovered skills with their paths

### Step 2: Selection

Interactive selection menu:
- View all discovered skills
- Select individual skills or all
- Confirm before proceeding

Use `--all` flag to skip selection and migrate all discovered skills.

### Step 3: Conflict Resolution

For each skill that already exists at the destination:
- **Overwrite**: Replace existing skill
- **Skip**: Keep existing skill, skip this one
- **Backup**: Create backup with timestamp, then overwrite

Use `--conflict-strategy <strategy>` to set a default strategy and avoid prompts.

### Step 4: Installation

Copies selected skills to destination:
- Preserves directory structure
- Maintains file permissions
- Copies all skill contents as-is

### Step 5: Report

Generates a migration report showing:
- Successfully migrated skills
- Skipped skills (with reason)
- Backed up skills (with backup location)
- Any errors encountered

## Scripts

Use the migration script:

- `scripts/migrate.sh` - Main migration script with interactive and non-interactive workflow

### Script Usage

```bash
scripts/migrate.sh [OPTIONS] <source-directory>

Options:
    -a, --all                 Migrate all discovered skills without prompting
    -c, --conflict-strategy   Set conflict resolution: skip, overwrite, backup
    -y, --yes                 Auto-confirm all prompts without interaction
    -l, --local               Install to local project (.opencode/skills/)
    -g, --global              Install to global directory (~/.config/opencode/skills/)
    -d, --dry-run             Preview changes without migrating
    -h, --help                Show help message

Interactive Mode (default):
    The script will prompt for skill selection, conflict resolution, and confirmation.

Non-Interactive Mode:
    Use -a/--all, -y/--yes, and -c/--conflict-strategy for automated usage.

Examples:
    # Interactive mode
    scripts/migrate.sh ~/my-skills
    
    # Non-interactive: migrate all
    scripts/migrate.sh ~/my-skills --all --yes
    
    # Non-interactive: migrate all, skip existing
    scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip
    
    # Non-interactive: migrate all, overwrite existing
    scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite
    
    # Dry run
    scripts/migrate.sh ~/my-skills --all --dry-run
    
    # Local project installation
    scripts/migrate.sh ~/my-skills --local --all --yes
```

## Target Locations

### Global Skills (Default)

Installed to: `~/.config/opencode/skills/`

- Available across all projects
- Shared OpenCode installation
- Best for commonly used skills

### Local Project Skills

Installed to: `./.opencode/skills/`

- Project-specific skills only
- Version controlled with project
- Team-shared within project

## Non-Interactive Mode

For use with opencode and coding agents, the script supports full automation:

### Flags for Automation

- `--all`: Skip skill selection and migrate all discovered skills
- `--yes`: Skip confirmation prompts and proceed automatically
- `--conflict-strategy <strategy>`: Set default conflict handling (skip/overwrite/backup)

### Example Automation Scenarios

**Migrate all skills, skip existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip
```

**Migrate all skills, overwrite existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite
```

**Migrate all skills, backup existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy backup
```

**Dry run to preview changes:**
```bash
scripts/migrate.sh ~/my-skills --all --dry-run
```

### Conflict Strategies

- `skip`: Keep existing skills, skip migrating those that already exist
- `overwrite`: Replace existing skills with the new versions
- `backup`: Create timestamped backups of existing skills before overwriting

## Important Notes

- Skills are copied as-is without validation
- File permissions are preserved during migration
- Backups are stored with timestamp: `skillname.backup.YYYYMMDD_HHMMSS`
- Empty directories and non-skill folders are ignored
- The script requires write permissions to the destination directory
- Use `--all`, `--yes`, and `--conflict-strategy` flags for non-interactive usage with opencode
- Non-interactive mode is ideal for automated workflows and CI/CD pipelines

## Troubleshooting

See `references/migration-guide.md` for detailed troubleshooting and advanced usage.