feat(skills): refresh marketplace release workflows
This commit is contained in:
+36
-192
@@ -1,218 +1,62 @@
|
||||
# Skill Sync Guide
|
||||
|
||||
## Overview
|
||||
仓库中的插件是团队技能的发布源，本机 `~/.claude/skills/` 是安装目标。个人技能保留在
|
||||
`skills-personal/` 或其他本机目录，不会进入公开 marketplace。
|
||||
|
||||
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
|
||||
git pull
|
||||
./install-skills.sh --dry-run
|
||||
./install-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
|
||||
安装器会复制完整技能目录，包括 `SKILL.md`、`references/`、`scripts/` 和 `assets/`。它用内容摘要区分仓库升级和本地修改：
|
||||
|
||||
## Sync Workflow
|
||||
- 目标未修改时，版本升级会自动安装。
|
||||
- 旧版只安装了 `SKILL.md` 时，会安全补齐仓库中的其他同源文件。
|
||||
- 目标存在本地修改时会跳过；确认覆盖后才使用 `--force`。
|
||||
- `--cleanup` 会删除状态文件记录中已从仓库移除的技能，使用前先运行 `--dry-run --cleanup`。
|
||||
|
||||
### 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
|
||||
./install-skills.sh --list
|
||||
./install-skills.sh --category dev
|
||||
```
|
||||
|
||||
### 3. Review Changes
|
||||
## 将本机技能发布到仓库
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
```
|
||||
不要批量复制整个 `~/.claude/skills/`。系统技能、第三方托管技能、包含机器路径或凭据的技能不应发布。
|
||||
|
||||
### 4. Commit & Push
|
||||
1. 选择确实属于本仓库、可供团队复用的技能。
|
||||
2. 在对应 `skills-*/<name>-plugin/` 下放置 `.claude-plugin/plugin.json` 和完整 `skills/` 目录。
|
||||
3. 清除用户名、绝对路径、内网地址、密钥标识和历史凭据；把环境差异改为从仓库配置解析。
|
||||
4. 更新插件版本并运行：
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Update skill: description of changes"
|
||||
git push
|
||||
```
|
||||
```bash
|
||||
python3 generate-marketplace.py
|
||||
claude plugin validate .
|
||||
git diff --check
|
||||
```
|
||||
|
||||
### 5. Team Updates
|
||||
5. 审核变更后通过分支和 PR 发布。
|
||||
|
||||
Team members update with:
|
||||
```bash
|
||||
/plugin marketplace update coolbuy-claude-plugins
|
||||
/plugin update <plugin-name>@coolbuy-claude-plugins
|
||||
```
|
||||
## 本地个人技能
|
||||
|
||||
## Automated Sync (Optional)
|
||||
`skills-personal/` 受 `.gitignore` 保护，仅供当前机器使用。生成器明确排除此目录，避免
|
||||
`marketplace.json` 引用公开克隆中不存在的文件。若个人技能要转为团队技能，应先按上面的发布流程完成脱敏和审核。
|
||||
|
||||
### 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
|
||||
先比较仓库源和 `~/.claude/skills/<name>/`。保留本地修改时将其整理成插件变更；确认丢弃时再对该次安装使用 `--force`。
|
||||
|
||||
chmod +x .git/hooks/pre-commit
|
||||
```
|
||||
**marketplace 没更新？**
|
||||
|
||||
### Cron Job (Scheduled)
|
||||
运行 `python3 generate-marketplace.py`，然后检查 `.claude-plugin/marketplace.json` 是否只包含受 Git 跟踪且真实存在的 source。
|
||||
|
||||
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.
|
||||
删除插件目录、重新生成 marketplace、提交变更。使用者随后执行 `./install-skills.sh --dry-run --cleanup`，确认后再去掉 `--dry-run`。
|
||||
|
||||
Reference in New Issue
Block a user