# Skill Sync Guide

## Overview

This guide explains how to keep your local skills (`~/.claude/skills/`) synchronized with the marketplace plugins.

## Quick Sync

```bash
cd /path/to/claude-marketplace
./sync-skills.sh
```

This will:
1. ✅ Compare local skills with marketplace plugins
2. ➕ Add new skills as plugins
3. 📝 Update changed skills
4. ✓ Skip unchanged plugins

## Sync Workflow

### 1. Edit Skills Locally

Work on your skills in `~/.claude/skills/`:
```bash
code ~/.claude/skills/my-skill/SKILL.md
```

### 2. Run Sync Script

```bash
cd ~/path/to/claude-marketplace
./sync-skills.sh
```

### 3. Review Changes

```bash
git status
git diff
```

### 4. Commit & Push

```bash
git add .
git commit -m "Update skill: description of changes"
git push
```

### 5. Team Updates

Team members update with:
```bash
/plugin marketplace update coolbuy-claude-plugins
/plugin update <plugin-name>@coolbuy-claude-plugins
```

## Automated Sync (Optional)

### Git Hook (Pre-commit)

Auto-sync when committing changes to skills:

```bash
# In your dotfiles/skills repo
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# Auto-sync skills to marketplace
~/path/to/claude-marketplace/sync-skills.sh
EOF

chmod +x .git/hooks/pre-commit
```

### Cron Job (Scheduled)

Sync daily at 9 AM:

```bash
crontab -e

# Add this line:
0 9 * * * cd ~/path/to/claude-marketplace && ./sync-skills.sh && git add . && git commit -m "Daily sync" && git push
```

## Skill Splitting Guidelines

From `~/.claude/CLAUDE.md`:

- **Token Limit**: Single skill ≤ 10,000 tokens
- **Check Size**: `wc -w ~/.claude/skills/<skill>/SKILL.md`
- **When to Split**: If > 7,500 words (≈10,000 tokens)

### Split Strategy

When a skill grows too large:

1. **Entry Skill** - Overview + command routing (<100 lines)
   - Example: `req/SKILL.md`

2. **Command Reference** - Detailed commands (<200 lines)
   - Example: `req-commands/SKILL.md`

3. **Workflow Guide** - Complete processes (<200 lines)
   - Example: `req-workflow/SKILL.md`

4. **Methodology** - Complex concepts (<150 lines)
   - Example: `req-review/SKILL.md`

## Troubleshooting

### Sync Script Fails

```bash
# Check permissions
ls -la sync-skills.sh

# Make executable
chmod +x sync-skills.sh

# Check paths
echo $HOME/.claude/skills
```

### marketplace.json Not Updated

```bash
# Manually regenerate
python3 generate-marketplace.py

# Or edit directly
code .claude-plugin/marketplace.json
```

### Git Conflicts

```bash
# Discard local changes
git checkout .claude-plugin/marketplace.json

# Or merge manually
git mergetool
```

## Best Practices

### 1. Descriptive Frontmatter

Always include in `SKILL.md`:
```yaml
---
name: skill-name
description: Clear, concise description of what this skill does
---
```

### 2. Version Bumping

When making significant changes:
```bash
# Update version in plugin.json
{
  "version": "1.1.0"  # was 1.0.0
}
```

### 3. Testing Before Sync

```bash
# Test skill locally first
/skill-name

# Then sync to marketplace
./sync-skills.sh
```

### 4. Commit Messages

Use clear, descriptive messages:
```bash
git commit -m "Add feishu-bitable plugin for table operations"
git commit -m "Update req-workflow with new approval process"
git commit -m "Fix: Correct PRD template in req-prd"
```

## Monitoring

### Check Sync Status

```bash
# Compare local vs marketplace
diff -qr ~/.claude/skills /tmp/claude-marketplace/plugins
```

### List Differences

```bash
# Find skills not in marketplace
comm -23 <(ls ~/.claude/skills | sort) <(ls plugins | sed 's/-plugin$//' | sort)

# Find plugins not in local
comm -13 <(ls ~/.claude/skills | sort) <(ls plugins | sed 's/-plugin$//' | sort)
```

## FAQ

**Q: Can I sync in reverse (marketplace → local)?**
A: Not recommended. Treat local skills as the source of truth.

**Q: What about binary files (images, scripts)?**
A: Copy them manually to the plugin directory, then commit.

**Q: How do I remove a plugin?**
A: Delete the plugin directory, regenerate marketplace.json, commit, and push.

**Q: Can I sync specific skills only?**
A: Modify `sync-skills.sh` to accept a skill name parameter.