439 lines
10 KiB
Markdown
439 lines
10 KiB
Markdown
# 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
|