Something rewrote every `/skills` into `~/.hanzo/skills` without checking what sat to its left, so the install docs sent readers to `~/.claude~/.hanzo/skills/`, the plugin dir became `hanzo-skills~/.hanzo/skills/`, and the issue tracker was advertised at `github.com/hanzoai~/.hanzo/skills/issues`. The same pass turned a noun in `commands/skills.md` into "skills", so `/skills` greeted the reader with "292 skills, 28 skills". Only the glued occurrences are reverted — `~/.hanzo/skills/` is a real path and the corpus keeps it. Three references point at files this tree does not have, and one recipe cloned `skills` and then cd'd into `hanzo-skills`. Co-authored-by: Hanzo Dev <[email protected]>
6.2 KiB
Migration Guide: Manual Installation → Plugin
This guide is for users who previously installed hanzo-skills manually using install.sh and are migrating to the new plugin system.
Why Migrate?
The plugin system provides:
- ✅ One-command installation - No scripts, no manual syncing
- ✅ Automatic updates - Pull latest version with
/plugin update - ✅ Cleaner installation - No files in
~/.claude/skillsor~/.claude/commands - ✅ Better isolation - Plugin data stays in
~/.claude/plugins/hanzo-skills/ - ✅ Version management - Track which version you're using
- ✅ Marketplace distribution - Discover and share plugins easily
Migration Steps
1. Backup Your Data (Optional)
If you've customized any skills or commands, back them up:
# Backup skills
cp -r ~/.claude/skills ~/.claude/skills.backup
# Backup commands
cp -r ~/.claude/commands ~/.claude/commands.backup
2. Uninstall Manual Installation
Remove the manually installed files:
# Remove skills directory
rm -rf ~/.claude/skills
# Remove /skills command
rm ~/.claude/commands/skills.md
Note: If you have other custom commands in ~/.claude/commands/, only remove skills.md:
ls ~/.claude/commands/ # Check what's there
rm ~/.claude/commands/skills.md # Remove only skills.md
3. Install Plugin
Install hanzo-skills as a plugin:
/plugin install https://github.com/hanzoai/skills
That's it! The plugin system will:
- Download all 292 skills to
~/.claude/plugins/hanzo-skills/skills/ - Register the
/skillscommand automatically - Make everything available immediately
4. Verify Installation
Check that the plugin is installed:
/plugin list
You should see:
hanzo-skills (v2.0.0) - 292 atomic skills with skill-based progressive loading
Test the /skills command:
/skills
You should see skill recommendations and categories.
5. Restore Customizations (If Any)
If you customized any skills, you can copy them to the plugin directory:
# Example: Restore a custom skill
cp ~/.claude/skills.backup/custom/my-skill.md \
~/.claude/plugins/hanzo-skills/skills/custom/my-skill.md
Note: The plugin directory is at ~/.claude/plugins/hanzo-skills/, not ~/.claude/skills/.
What Changed
Installation Location
Before (Manual):
~/.claude/skills/ # Skills directory
~/.claude/commands/ # Commands directory
After (Plugin):
~/.claude/plugins/hanzo-skills/skills/ # Skills
~/.claude/plugins/hanzo-skills/commands/ # Commands
Installation Method
Before (Manual):
git clone https://github.com/hanzoai/skills
cd skills
./commands/install.sh
After (Plugin):
/plugin install https://github.com/hanzoai/skills
Updating
Before (Manual):
cd ~/src/hanzo-skills
git pull
./commands/install.sh # Re-run install
After (Plugin):
/plugin update hanzo-skills
Uninstallation
Before (Manual):
./commands/uninstall.sh
After (Plugin):
/plugin uninstall hanzo-skills
What Stayed the Same
Skills Structure
The 292 skills across 31 categories are identical:
- Same skill architecture
- Same progressive loading
- Same skill content and guidance
- Same category organization
Skills Discovery
All discovery mechanisms work exactly the same:
/skillscommand (context-aware recommendations)/skills frontend(browse by category)/skills postgres(search by keyword)- Automatic skill activation
- Manual skill reading with
cat
Compatibility
All existing workflows continue to work:
- Skill skills still activate based on project context
- Skills still compose with each other
- All 28 skills, 31 categories, 292 skills unchanged
Troubleshooting
/skills command not found after migration
Solution:
# Verify plugin is installed
/plugin list
# If not listed, install it
/plugin install https://github.com/hanzoai/skills
# Restart Claude Code session
Skills not showing up
Solution:
# Check plugin directory exists
ls ~/.claude/plugins/hanzo-skills/skills/
# If empty, reinstall plugin
/plugin uninstall hanzo-skills
/plugin install https://github.com/hanzoai/skills
Want to keep both installations?
You can keep the manual installation in ~/.claude/skills/ for reference, but:
- Only the plugin version will be used by
/skillscommand - Skill skills will activate from plugin location
- This may cause confusion - recommended to remove manual installation
Rollback (If Needed)
If you need to rollback to manual installation:
# 1. Uninstall plugin
/plugin uninstall hanzo-skills
# 2. Restore backup
cp -r ~/.claude/skills.backup ~/.claude/skills
cp ~/.claude/commands.backup/skills.md ~/.claude/commands/skills.md
# 3. Restart Claude Code
Questions?
How do I know which version I have?
Plugin:
/plugin list # Shows version number
Manual:
cat ~/.claude/skills/README.md | grep "Version:"
Can I install both?
Technically yes, but not recommended. The plugin system will take precedence for commands and skill discovery.
Will my custom skills be lost?
No, but you need to manually copy them from ~/.claude/skills/ to ~/.claude/plugins/hanzo-skills/skills/ after installing the plugin.
How do I contribute updates?
Same as before:
- Fork the repository: https://github.com/hanzoai/skills
- Make changes to skills
- Submit a pull request
Once merged, users can update with /plugin update hanzo-skills.
Next Steps
After migration:
- Explore the plugin system:
/plugin list,/plugin help - Test your workflows with the plugin-based installation
- Remove backups if everything works:
rm -rf ~/.claude/skills.backup ~/.claude/commands.backup - Update any documentation or personal notes about installation
Support
If you encounter issues during migration:
- Check this guide's troubleshooting section
- Review plugin documentation:
cat ~/.claude/plugins/hanzo-skills/PLUGIN.md - Open an issue: https://github.com/hanzoai/skills/issues
Migration complete! You're now using hanzo-skills as a Claude Code plugin with cleaner installation, automatic updates, and better version management.