# 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`。