63 lines
2.4 KiB
Markdown
63 lines
2.4 KiB
Markdown
# Skill Sync Guide
|
|
|
|
仓库中的插件是团队技能的发布源，本机 `~/.claude/skills/` 是安装目标。个人技能保留在
|
|
`skills-personal/` 或其他本机目录，不会进入公开 marketplace。
|
|
|
|
## 从仓库更新本机
|
|
|
|
```bash
|
|
git pull
|
|
./install-skills.sh --dry-run
|
|
./install-skills.sh
|
|
```
|
|
|
|
安装器会复制完整技能目录，包括 `SKILL.md`、`references/`、`scripts/` 和 `assets/`。它用内容摘要区分仓库升级和本地修改：
|
|
|
|
- 目标未修改时，版本升级会自动安装。
|
|
- 旧版只安装了 `SKILL.md` 时，会安全补齐仓库中的其他同源文件。
|
|
- 目标存在本地修改时会跳过；确认覆盖后才使用 `--force`。
|
|
- `--cleanup` 会删除状态文件记录中已从仓库移除的技能，使用前先运行 `--dry-run --cleanup`。
|
|
|
|
按分类安装或查看清单：
|
|
|
|
```bash
|
|
./install-skills.sh --list
|
|
./install-skills.sh --category dev
|
|
```
|
|
|
|
## 将本机技能发布到仓库
|
|
|
|
不要批量复制整个 `~/.claude/skills/`。系统技能、第三方托管技能、包含机器路径或凭据的技能不应发布。
|
|
|
|
1. 选择确实属于本仓库、可供团队复用的技能。
|
|
2. 在对应 `skills-*/<name>-plugin/` 下放置 `.claude-plugin/plugin.json` 和完整 `skills/` 目录。
|
|
3. 清除用户名、绝对路径、内网地址、密钥标识和历史凭据；把环境差异改为从仓库配置解析。
|
|
4. 更新插件版本并运行：
|
|
|
|
```bash
|
|
python3 generate-marketplace.py
|
|
claude plugin validate .
|
|
git diff --check
|
|
```
|
|
|
|
5. 审核变更后通过分支和 PR 发布。
|
|
|
|
## 本地个人技能
|
|
|
|
`skills-personal/` 受 `.gitignore` 保护，仅供当前机器使用。生成器明确排除此目录，避免
|
|
`marketplace.json` 引用公开克隆中不存在的文件。若个人技能要转为团队技能，应先按上面的发布流程完成脱敏和审核。
|
|
|
|
## 常见问题
|
|
|
|
**本地修改被跳过怎么办？**
|
|
|
|
先比较仓库源和 `~/.claude/skills/<name>/`。保留本地修改时将其整理成插件变更；确认丢弃时再对该次安装使用 `--force`。
|
|
|
|
**marketplace 没更新？**
|
|
|
|
运行 `python3 generate-marketplace.py`，然后检查 `.claude-plugin/marketplace.json` 是否只包含受 Git 跟踪且真实存在的 source。
|
|
|
|
**如何移除技能？**
|
|
|
|
删除插件目录、重新生成 marketplace、提交变更。使用者随后执行 `./install-skills.sh --dry-run --cleanup`，确认后再去掉 `--dry-run`。
|