Add skills
This commit is contained in:
@@ -0,0 +1,438 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user