.dotfiles/.config/opencode/skills/skill-migrator/references/migration-guide.md

Skill Migration Guide

Comprehensive guide for migrating LLM tools and skills to OpenCode.

Table of Contents

1. Quick Start
2. Usage Examples
3. Interactive Workflow
4. Conflict Resolution
5. Troubleshooting
6. Advanced Usage

Quick Start

Basic Migration

Migrate all skills from a directory to global OpenCode:

# Discover and migrate skills
~/.config/opencode/skills/skill-migrator/scripts/migrate.sh /path/to/skills

# Or if you're in the skill-migrator directory
./scripts/migrate.sh /path/to/skills

Migrate to Local Project

./scripts/migrate.sh /path/to/skills --local

Usage Examples

Example 1: Migrating from Backup

You have a backup of skills in ~/backups/opencode-skills/:

./scripts/migrate.sh ~/backups/opencode-skills

Workflow:

1. Script discovers all skills containing SKILL.md
2. Lists discovered skills with numbers
3. You select which to migrate (or 'a' for all)
4. For existing skills, choose: overwrite/skip/backup
5. Migration completes with a report

Example 2: Preview Before Migrating

See what would be migrated without making changes:

./scripts/migrate.sh ~/external-tools --dry-run

This shows:

• Which skills would be discovered
• Which already exist at destination
• No actual changes are made

Example 3: Selective Migration

Migrate only specific skills:

./scripts/migrate.sh ~/my-tools
# At selection prompt, enter: 1,3,5
# Only skills 1, 3, and 5 will be migrated

Example 4: Local Development

Working on a project that needs specific skills:

# In your project directory
./scripts/migrate.sh ~/project-skills --local

# Skills installed to ./.opencode/skills/
# Can be version controlled with your project

Interactive Workflow

Discovery Phase

The script searches recursively for directories containing SKILL.md:

ℹ Discovering skills in: /home/user/external-skills
✓ Found 5 skill(s)

Discovered Skills:
==================
 1. docker-helper               (/home/user/external-skills/docker-helper)
 2. git-workflow                (/home/user/external-skills/workflows/git-workflow)
 3. api-tester                  (/home/user/external-skills/devtools/api-tester)
 4. doc-generator               (/home/user/external-skills/docs/doc-generator)
 5. test-validator              (/home/user/external-skills/qa/test-validator)

Selection Phase

Choose which skills to migrate:

Select skills to migrate:
  [a] - Migrate all
  [1-5] - Select specific skill(s) by number (comma-separated)
  [q] - Quit

Your choice: 1,3,5

Confirmation

Before proceeding:

Ready to migrate 3 skill(s).
Continue? [Y/n]: Y

Migration Progress

Live progress as skills are migrated:

ℹ Migrating: docker-helper
⚠ Skill already exists: docker-helper
  Location: ~/.config/opencode/skills/docker-helper

Options:
  [o] - Overwrite (replace existing)
  [s] - Skip (keep existing)
  [b] - Backup (create backup, then overwrite)

Your choice [o/s/b]: b
ℹ Backed up to: ~/.config/opencode/skills/docker-helper.backup.20240319_143052
✓ Migrated: docker-helper

ℹ Migrating: api-tester
✓ Migrated: api-tester

ℹ Migrating: test-validator
✓ Migrated: test-validator

Final Report

========================================
        MIGRATION REPORT
========================================

✓ Successfully Migrated (3):
  • docker-helper
  • api-tester
  • test-validator

ℹ Backed Up (1):
  • docker-helper -> ~/.config/opencode/skills/docker-helper.backup.20240319_143052

Target Directory: ~/.config/opencode/skills
========================================

Conflict Resolution

When Conflicts Occur

A conflict happens when a skill with the same name already exists at the destination.

Options

1. Overwrite

• When to use: The new version is newer/better, or you don't need the old one
• Result: Existing skill is completely replaced
• Risk: You lose the old version permanently

2. Skip

• When to use: You want to keep the existing skill as-is
• Result: New skill is not migrated
• Use case: The existing skill has customizations you want to keep

3. Backup

• When to use: You want both versions (safe option)
• Result: Old skill backed up with timestamp, new skill installed
• Backup location: ~/.config/opencode/skills/skillname.backup.YYYYMMDD_HHMMSS

Best Practices

• Always choose backup when unsure - you can manually merge later
• Use skip if you've customized the existing skill
• Use overwrite if the source is definitely newer/correct

Troubleshooting

Issue: "No skills found"

Symptoms:

⚠ No skills found in: /path/to/source
ℹ Looking for directories containing 'SKILL.md'

Solutions:

1. Verify source structure:

   # Check if SKILL.md files exist
   find /path/to/source -name "SKILL.md" -type f
   

2. Check file permissions:

   # Ensure you can read the directory
   ls -la /path/to/source
   

3. Verify path is correct:

   # Make sure path exists
   ls -d /path/to/source
   

Issue: "Permission denied"

Symptoms:

✗ Cannot write to target directory

Solutions:

1. Check directory permissions:

   ls -ld ~/.config/opencode/skills
   

2. Fix permissions:

   # For global directory
   mkdir -p ~/.config/opencode/skills
   chmod 755 ~/.config/opencode/skills
   
   # For local directory
   mkdir -p .opencode/skills
   chmod 755 .opencode/skills
   

3. Run with appropriate user: Ensure you're running as the user who owns the OpenCode config

Issue: Script hangs or no prompt

Symptoms: Script stops without showing selection menu

Solutions:

1. Ensure terminal is interactive:

   # Check if stdin is a terminal
   [ -t 0 ] && echo "Interactive" || echo "Not interactive"
   

2. Run in proper terminal: Don't run from non-interactive contexts (CI/CD, scripts without TTY)

3. Use --dry-run first:

   ./scripts/migrate.sh /path --dry-run
   

Issue: Skills not appearing in OpenCode

Symptoms: Migration succeeds but OpenCode doesn't recognize new skills

Solutions:

1. Check skill structure:

   # Verify SKILL.md exists
   ls ~/.config/opencode/skills/new-skill/SKILL.md
   

2. Check SKILL.md format:

   • Must start with YAML frontmatter (---)
   • Must have name: field
   • Must have description: field (20-1024 chars)

3. Validate the skill:

   ~/.config/opencode/skills/skill-builder/scripts/validate-skill.sh \
     ~/.config/opencode/skills/new-skill
   

4. Restart OpenCode if using a GUI/IDE plugin

Issue: Backup not created

Symptoms: Chose 'backup' option but can't find backup

Solutions:

1. Check backup location:

   ls -la ~/.config/opencode/skills/*.backup.*
   

2. Check timestamp format: Backups use format: skillname.backup.YYYYMMDD_HHMMSS

3. Verify not in dry-run: Backups are only created during actual migration, not dry-run

Advanced Usage

Batch Migration Script

Create a wrapper for recurring migrations:

#!/bin/bash
# migrate-from-backup.sh

BACKUP_DIR="${HOME}/backups/opencode-skills"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"

# Always backup before overwriting
export MIGRATOR_DEFAULT_ACTION="backup"

# Run migration
"$MIGRATOR" "$BACKUP_DIR" "$@"

Automated Sync

Sync skills from a git repository:

#!/bin/bash
# sync-skills.sh

SKILLS_REPO="https://github.com/company/shared-opencode-skills.git"
TEMP_DIR="/tmp/opencode-skills-sync"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"

# Clone latest
rm -rf "$TEMP_DIR"
git clone "$SKILLS_REPO" "$TEMP_DIR"

# Dry run first
"$MIGRATOR" "$TEMP_DIR/skills" --dry-run

# Ask for confirmation
read -p "Proceed with migration? [y/N]: " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
    "$MIGRATOR" "$TEMP_DIR/skills"
fi

# Cleanup
rm -rf "$TEMP_DIR"

Selective Auto-Backup

Always backup certain critical skills:

#!/bin/bash
# safe-migrate.sh

CRITICAL_SKILLS=("production-deploy" "database-migration" "security-scan")
SOURCE_DIR="$1"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"

# Pre-backup critical skills
for skill in "${CRITICAL_SKILLS[@]}"; do
    skill_path="${HOME}/.config/opencode/skills/${skill}"
    if [[ -d "$skill_path" ]]; then
        timestamp=$(date +"%Y%m%d_%H%M%S")
        cp -r "$skill_path" "${skill_path}.pre-migration.${timestamp}"
        echo "Pre-backed up: $skill"
    fi
done

# Run migration
"$MIGRATOR" "$SOURCE_DIR"

Migration with Validation

Validate skills after migration:

#!/bin/bash
# migrate-and-validate.sh

SOURCE_DIR="$1"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
VALIDATOR="${HOME}/.config/opencode/skills/skill-builder/scripts/validate-skill.sh"
TARGET_DIR="${HOME}/.config/opencode/skills"

# Migrate
"$MIGRATOR" "$SOURCE_DIR"

# Validate all migrated skills
echo ""
echo "Validating migrated skills..."
for skill_dir in "$TARGET_DIR"/*/; do
    skill_name=$(basename "$skill_dir")
    if [[ -f "$skill_dir/SKILL.md" ]]; then
        echo "Validating: $skill_name"
        if ! "$VALIDATOR" "$skill_dir" 2>/dev/null; then
            echo "⚠ $skill_name has validation issues"
        fi
    fi
done

Tips and Best Practices

1. Always use --dry-run first when migrating from a new source
2. Keep backups until you've verified skills work in OpenCode
3. Use local skills for project-specific tools
4. Use global skills for commonly used utilities
5. Document your skills with clear descriptions for better OpenCode integration
6. Test migrated skills by asking OpenCode to use them

See Also

• SKILL.md - Main skill documentation
• skill-builder skill - For validating and creating skills
• OpenCode documentation for skill development