237 lines
7.0 KiB
Markdown
237 lines
7.0 KiB
Markdown
---
|
|
name: skill-migrator
|
|
description: 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
|
|
license: MIT
|
|
compatibility: opencode
|
|
metadata:
|
|
category: tools
|
|
version: "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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip
|
|
```
|
|
|
|
**Migrate all skills, overwrite existing:**
|
|
```bash
|
|
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite
|
|
```
|
|
|
|
**Migrate all skills, backup existing:**
|
|
```bash
|
|
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy backup
|
|
```
|
|
|
|
**Dry run to preview changes:**
|
|
```bash
|
|
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.
|