.dotfiles/.config/opencode/skills/skill-migrator/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
skill-migrator	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	MIT	opencode	category version tools 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:

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:

# 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:

# 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:

# 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

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:

scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip

Migrate all skills, overwrite existing:

scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite

Migrate all skills, backup existing:

scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy backup

Dry run to preview changes:

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.