move claude-marketplace to ai-proj-helper

2026-03-12 21:42:30 +08:00
parent d7b6835e1d
commit 43585b8504
188 changed files with 39510 additions and 0 deletions
--- a/SYNC-GUIDE.md
+++ b/SYNC-GUIDE.md
@@ -0,0 +1,218 @@
+# 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.