From 13288318066b4299dc18305c65abe4cffcbf5ac6 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 29 Jan 2026 16:21:45 +0000 Subject: [PATCH] Add comprehensive sync guide for cross-machine setup --- SYNC-GUIDE.md | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 SYNC-GUIDE.md diff --git a/SYNC-GUIDE.md b/SYNC-GUIDE.md new file mode 100644 index 0000000..73de3a1 --- /dev/null +++ b/SYNC-GUIDE.md @@ -0,0 +1,350 @@ +# Skillshare Cross-Machine Sync Guide + +**Repository**: https://gitea.pressmess.duckdns.org/admin/claude-skills +**Built-in Feature**: Skillshare has native git support for cross-machine sync + +--- + +## 🎯 How It Works + +Skillshare automatically: +1. Syncs skills from central source to all AI tools on current machine (Claude, Moltbot, etc.) +2. Pushes/pulls skills to/from git remote for cross-machine sync +3. Handles conflicts and merging + +**Two-Layer Sync**: +``` +Git Remote (Gitea) + ↕ (skillshare push/pull) +Source: ~/.config/skillshare/skills + ↕ (skillshare sync) +Targets: ~/.claude/skills, moltbot/skills, etc. +``` + +--- + +## 🚀 Setup on New Machine + +### Initial Setup (First Time Only) + +```bash +# Install skillshare +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh + +# Initialize with git remote +skillshare init --source ~/.config/skillshare/skills \ + --all-targets \ + --git \ + --remote https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git + +# Pull skills from Gitea and sync to all AI tools +skillshare pull --remote +``` + +### Or Manual Setup + +```bash +# 1. Install skillshare +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh + +# 2. Initialize without remote +skillshare init --no-copy --all-targets --git + +# 3. Add remote manually +cd ~/.config/skillshare/skills +git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git + +# 4. Pull and sync +skillshare pull --remote +``` + +--- + +## 🔄 Daily Workflow + +### Pull Changes from Other Machines + +```bash +# Pull from Gitea and auto-sync to all AI tools +skillshare pull --remote + +# Preview first (dry run) +skillshare pull --remote --dry-run +``` + +This automatically: +1. Pulls from Gitea +2. Syncs to Claude Code (`~/.claude/skills`) +3. Syncs to Moltbot (`/mnt/nvme/projects/active/moltbot/skills`) +4. Syncs to any other configured targets + +### Push Changes to Other Machines + +```bash +# Add new skill +skillshare new my-helper-skill + +# Edit the skill +nano ~/.config/skillshare/skills/my-helper-skill/SKILL.md + +# Sync locally first (to Claude, Moltbot, etc.) +skillshare sync + +# Commit and push to Gitea +skillshare push -m "Add my-helper-skill" +``` + +### Quick Status Check + +```bash +# See sync status +skillshare status + +# See what would change +skillshare sync --dry-run + +# Check git status +cd ~/.config/skillshare/skills && git status +``` + +--- + +## 📝 Common Workflows + +### Create New Skill + +```bash +# 1. Create skill +skillshare new cool-feature + +# 2. Edit SKILL.md +nano ~/.config/skillshare/skills/cool-feature/SKILL.md + +# 3. Sync to local AI tools +skillshare sync + +# 4. Push to Gitea for other machines +skillshare push -m "Add cool-feature skill" +``` + +### Install Skill from GitHub + +```bash +# Install from public repo +skillshare install github.com/user/awesome-skill + +# Sync to local tools +skillshare sync + +# Push to your Gitea for team +skillshare push -m "Add awesome-skill from community" +``` + +### Pull Skill from Another AI Tool + +```bash +# Import skill from Moltbot to source +skillshare pull moltbot + +# Sync to other tools +skillshare sync + +# Push to Gitea +skillshare push -m "Import skill from Moltbot" +``` + +--- + +## 🔧 Advanced Operations + +### Update All Tracked Repositories + +```bash +# Update skills installed from repos +skillshare update --all + +# Sync to local tools +skillshare sync + +# Push updates to Gitea +skillshare push -m "Update tracked skills" +``` + +### Compare with Remote + +```bash +cd ~/.config/skillshare/skills +git fetch origin +git diff origin/main +``` + +### Rollback to Previous Version + +```bash +cd ~/.config/skillshare/skills +git log --oneline +git checkout abc123 -- skillname/ +skillshare sync +skillshare push -m "Rollback skillname" +``` + +--- + +## 🆘 Troubleshooting + +### Skills Not Syncing Locally + +```bash +# Check status +skillshare status + +# Force sync +skillshare sync --force + +# Check for errors +skillshare doctor +``` + +### Remote Push Failed + +```bash +# Check git status +cd ~/.config/skillshare/skills +git status + +# Pull first, then push +skillshare pull --remote +skillshare push -m "Your message" +``` + +### Merge Conflicts + +```bash +# Skillshare will show conflict +skillshare pull --remote + +# Resolve manually +cd ~/.config/skillshare/skills +nano conflicted-skill/SKILL.md # Remove <<<< ==== >>>> markers +git add . +git commit -m "Resolve conflict" +git push origin main + +# Then sync to local tools +skillshare sync +``` + +### Authentication Failed + +```bash +# Update remote URL +cd ~/.config/skillshare/skills +git remote set-url origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git +``` + +### Reset to Remote (Nuclear Option) + +```bash +cd ~/.config/skillshare/skills +git fetch origin +git reset --hard origin/main +skillshare sync --force +``` + +--- + +## 📊 Comparison: Skills vs Agents + +| Aspect | Skills (Skillshare) | Agents (Git) | +|--------|-------------------|--------------| +| **Location** | `~/.config/skillshare/skills/` | `~/.claude/agents/` | +| **What** | Task definitions for AI | AI assistant configurations | +| **Local Sync** | Auto-sync to Claude/Moltbot | N/A (single location) | +| **Cross-Machine** | `skillshare push/pull` | `git push/pull` | +| **Repository** | claude-skills | claude-agents | +| **Management** | Skillshare CLI | Git commands | + +--- + +## 🎓 Best Practices + +### 1. Always Pull Before Creating + +```bash +skillshare pull --remote # Get latest from other machines +skillshare new my-skill # Create new skill +``` + +### 2. Sync Locally Before Pushing + +```bash +skillshare sync # Test on local AI tools first +skillshare push -m "msg" # Then share with other machines +``` + +### 3. Use Descriptive Commit Messages + +```bash +skillshare push -m "Add database-helper skill for PostgreSQL queries" +# Not: skillshare push -m "update" +``` + +### 4. Regular Sync Schedule + +- **Start of day**: `skillshare pull --remote` +- **After changes**: `skillshare sync && skillshare push -m "..."` +- **End of day**: `skillshare push -m "..."` + +### 5. Use Dry Run for Safety + +```bash +skillshare pull --remote --dry-run # Preview changes +skillshare sync --dry-run # Preview local sync +``` + +--- + +## 🚀 Quick Reference + +### Essential Commands + +| Task | Command | +|------|---------| +| Pull from Gitea | `skillshare pull --remote` | +| Push to Gitea | `skillshare push -m "message"` | +| Sync to AI tools | `skillshare sync` | +| Check status | `skillshare status` | +| Create skill | `skillshare new skillname` | +| List skills | `skillshare list --verbose` | + +### Setup Commands + +| Task | Command | +|------|---------| +| Init on new machine | `skillshare init --all-targets --git` | +| Add remote | `cd ~/.config/skillshare/skills && git remote add origin ` | +| First pull | `skillshare pull --remote` | + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| Conflicts | Edit files, remove markers, `git commit`, `skillshare sync` | +| Auth failed | `git remote set-url origin ` | +| Out of sync | `skillshare pull --remote && skillshare sync` | + +--- + +## 📚 Resources + +- **Skillshare Repo**: https://github.com/runkids/skillshare +- **Skills Gitea**: https://gitea.pressmess.duckdns.org/admin/claude-skills +- **Agents Gitea**: https://gitea.pressmess.duckdns.org/admin/claude-agents +- **Local Config**: `~/.config/skillshare/config.yaml` +- **Source Directory**: `~/.config/skillshare/skills/` + +--- + +**Last Updated**: 2026-01-29 +**Version**: 1.0 +**Maintained By**: admin