# 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