# Skill Migration Guide

Comprehensive guide for migrating LLM tools and skills to OpenCode.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Usage Examples](#usage-examples)
3. [Interactive Workflow](#interactive-workflow)
4. [Conflict Resolution](#conflict-resolution)
5. [Troubleshooting](#troubleshooting)
6. [Advanced Usage](#advanced-usage)

## Quick Start

### Basic Migration

Migrate all skills from a directory to global OpenCode:

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

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

## Usage Examples

### Example 1: Migrating from Backup

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

```bash
./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:

```bash
./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:

```bash
./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:

```bash
# 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:**
   ```bash
   # Check if SKILL.md files exist
   find /path/to/source -name "SKILL.md" -type f
   ```

2. **Check file permissions:**
   ```bash
   # Ensure you can read the directory
   ls -la /path/to/source
   ```

3. **Verify path is correct:**
   ```bash
   # Make sure path exists
   ls -d /path/to/source
   ```

### Issue: "Permission denied"

**Symptoms:**
```
✗ Cannot write to target directory
```

**Solutions:**

1. **Check directory permissions:**
   ```bash
   ls -ld ~/.config/opencode/skills
   ```

2. **Fix permissions:**
   ```bash
   # 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:**
   ```bash
   # 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:**
   ```bash
   ./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:**
   ```bash
   # 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:**
   ```bash
   ~/.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:**
   ```bash
   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:

```bash
#!/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:

```bash
#!/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:

```bash
#!/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:

```bash
#!/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