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