219 lines
4.0 KiB
Markdown
219 lines
4.0 KiB
Markdown
# 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.
|