ai-proj-helper/SYNC-GUIDE.md

Skill Sync Guide

Overview

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

Quick Sync

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/:

code ~/.claude/skills/my-skill/SKILL.md

2. Run Sync Script

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

3. Review Changes

git status
git diff

4. Commit & Push

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

5. Team Updates

Team members update with:

/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:

# 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:

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

# Check permissions
ls -la sync-skills.sh

# Make executable
chmod +x sync-skills.sh

# Check paths
echo $HOME/.claude/skills

marketplace.json Not Updated

# Manually regenerate
python3 generate-marketplace.py

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

Git Conflicts

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

# Or merge manually
git mergetool

Best Practices

1. Descriptive Frontmatter

Always include in SKILL.md:

---
name: skill-name
description: Clear, concise description of what this skill does
---

2. Version Bumping

When making significant changes:

# Update version in plugin.json
{
  "version": "1.1.0"  # was 1.0.0
}

3. Testing Before Sync

# Test skill locally first
/skill-name

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

4. Commit Messages

Use clear, descriptive messages:

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

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

List Differences

# 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.