admin/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive sync guide for cross-machine setup

Browse Source
This commit is contained in:
admin
2026-01-29 16:21:45 +00:00
parent b746c33c5d
commit 1328831806
1 changed files with 350 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
SYNC-GUIDE.md Normal file
View File

@@ -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 <url>` |
| First pull | `skillshare pull --remote` |
### Troubleshooting
| Issue | Solution |
|-------|----------|
| Conflicts | Edit files, remove markers, `git commit`, `skillshare sync` |
| Auth failed | `git remote set-url origin <url-with-password>` |
| 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