update-project-skills

更新项目技能

通过当前 skills.sh CLI，将目标项目中已安装的每项技能更新到最新发布版本，然后根据 https://github.com/toy-crane/skills 对照 Toycrane 技能集，并将其已安装技能所包含的自定义 Agent 同步到 Claude Code 和 Codex。

将 .agents/skills 视为项目技能的规范副本。CLI 会通过 .claude/skills 下的相对链接，将相同的技能文件提供给 Claude Code。skills-lock.json 记录 CLI 安装的每项技能及其来源。将 source 为 toy-crane/skills 的条目视为由 Toycrane 管理，其余条目均视为第三方技能。没有锁定条目的技能和 Agent 均属于项目本地内容；除非用户明确批准采用某个名称，否则请保留它们。

运行 CLI

以下每条命令均使用当前发布的 CLI，以 <runner> skills@latest 的形式运行。根据目标项目的包管理器选择 <runner>：bun 对应 bunx，pnpm 对应 pnpm dlx，其他情况使用 npx -y。如果 package.json 通过 devEngines 指定了其他包管理器，npm 会在 CLI 启动前以 EBADDEVENGINES 错误中止 npx。

更新所有已安装的技能

1. 根据请求路径或当前目录确定目标 Git 仓库。更改前先阅读仓库中的说明并检查其状态。

2. 检查已安装和上游技能清单：

   <runner> skills@latest list --json
   <runner> skills@latest add toy-crane/skills --list
   

   读取项目的 skills-lock.json。上游清单是当前发布的 Toycrane 技能集；忽略源代码仓库 .agents/skills 下仅用于开发的依赖项。

3. 在一次限定于项目的调用中，就地更新所有已锁定技能，无论其来源为何：

   <runner> skills@latest update -p -y
   

   CLI 会刷新每个记录了 skillPath 的锁定条目；每个来源只克隆一次，并为当前客户端以及通用 .agents 副本重新安装。现有的 .claude/skills 链接为相对链接，因此仍会有效。将以下三部分输出纳入最终报告：每项技能的结果；因安装时尚未跟踪 skillPath 而无法就地更新的条目（附上 CLI 打印的重新安装提示）；以及 CLI 报告的上游已删除技能。按原样保留后两组的状态；是否重新安装或删除由用户决定。

对照 Toycrane 技能集

将已发布的 Toycrane 清单与锁定文件进行对照分类：

• 安装每项本地缺失的全新已发布通用技能。
• 仅当 package.json 依赖 expo 或 react-native 时，才安装来自 expo 组的全新已发布技能。技术栈检测只决定是否安装新技能；即使不再检测到相应技术栈，也要继续更新已管理的特定技术栈技能。
• 如果某个已发布的 Toycrane 技能名称已存在于本地，但没有对应的锁定条目，则视为名称冲突。显示其路径并先征求用户同意，再决定是否采用。
• 从项目中退役所有已锁定但不再发布的 Toycrane 技能。

通过一次明确的调用安装新技能，以排除不符合技术栈条件的技能和未经批准的冲突名称；然后从整个项目中移除已退役的名称：

<runner> skills@latest add toy-crane/skills \
  --skill <new-skill-name> [<new-skill-name> ...] \
  --agent codex claude-code \
  -y
<runner> skills@latest remove <retired-skill-name> [<retired-skill-name> ...] -y

退役时不要指定作用范围。按 Agent 限定范围移除可能会留下规范 .agents 副本和锁定条目。

协调配套 Agent

从此技能的最新项目副本运行同步器：

python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
  --project <project-root> \
  [--retired-skill <retired-skill-name> ...]

对于上一轮协调中移除的每个由 Toycrane 管理的技能，追加一个 --retired-skill。这样，在 skills-lock.json 不再包含这些技能后，项目级 Agent 清单便可以退役相应的技能声明。

脚本只扫描 skills-lock.json 能证明由 Toycrane 管理的已安装技能。技能通过 companion-agents/manifest.json 声明配套 Agent；脚本会将其原生定义复制到 .claude/agents/<name>.md 和 .codex/agents/<name>.toml，在 .agents/toycrane-agents-lock.json 中记录所有权，并在项目已有 .agent-sync/manifest.json 时协调 shared_skills 和 shared_agents。

所有权锁授权后续刷新和退役这些确切的 Agent 名称。其他 Agent 文件和清单条目仍归项目所有。如果脚本报告存在未归属的冲突，请列出每个冲突路径，并请求批准对应名称。获得批准后，只接管获批的名称：

python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
  --project <project-root> \
  --adopt <approved-agent-name>

对于多个分别获批的名称，重复使用 --adopt。绝不可根据内容相同或清单中已有声明推断已获批准。冲突检查会核对每个原生 Agent 定义内部声明的名称，而不只检查文件名。接管后，脚本会移除获批身份在其他路径中的原生定义，再写入其规范的 Claude Code 和 Codex 文件对。

验证结果

• 重新运行 <runner> skills@latest list --json。

• 确认每个当前的 Toycrane 技能都存在于 .agents/skills 中，并在 skills-lock.json 中注明来源为 toy-crane/skills；同时确认 .claude/skills/<name> 是指向 ../../.agents/skills/<name> 的相对链接。

• 确认已退役的 Toycrane 技能不在锁文件和两个技能路径中；第三方锁定条目仍注明其原始来源；项目本地技能保持不变。

• 运行配套检查：

  python3 .agents/skills/update-project-skills/scripts/sync_companion_agents.py \
    --project <project-root> \
    --check
  

• 如果 .agent-sync/manifest.json 存在，请在配套检查后运行仓库的 Agent 同步检查。确认 shared_skills 列出了所有当前由 Toycrane 管理的技能，shared_agents 列出了所有配套 Agent。

• 检查完整的 Git 差异。按技能报告是否有改动及改动规模（使用 git diff --stat 即可），然后列出更新跳过的条目和上游删除警告。之后遵循仓库的提交政策。

• 如果当前 Claude Code 或 Codex 会话无法识别新安装的自定义 Agent，请完成更新，并说明需要启动新会话后才能测试 Agent 路由。

限制

• 所有更改仅限项目本地；绝不可使用 --global 或 -g。
• 第三方技能只能通过就地更新进行更改。新增第三方技能或移除上游已不存在的技能，必须等用户明确提出请求并指明技能名称。
• 将 skills-lock.json、.agents/toycrane-agents-lock.json（若存在）、已更新的技能和受管理的 Agent 文件一起提交，以确保所有权记录持久有效。
• 如果锁文件无法证明某个工件归 Toycrane 所有，未经对该名称的明确批准，不得将其移除或覆盖。
• 除非用户要求，否则不要推送。