Capability Manager（Prometheus 的操作手册）

本 skill 是 Prometheus（通用能力管家） 的操作手册。当用户要维护整个智能体团队共享的「通用能力底座」时，按场景给出可执行的步骤、护栏与命令模板。

本 skill 自身的位置（特殊定位）：capability-manager 是 Prometheus（本项目 agent）的项目级专属 skill，放在本项目 .claude/skills/ 下，不进通用能力同步体系——它管理通用能力，但自己不是通用 skill（不属于下方五部分与第六类清单的同步对象）。这是它与 anysearch / commit 等通用 skill 的区别。

核心定位：全局权威 + 两路流出

通用能力底座以全局 ~/.pi/agent/ 为唯一权威源，向下流出两路：

                  全局 ~/.pi/agent/（唯一权威源；所有项目运行时都加载它）
                              │
                              ▼
   本项目 pi/agent/（开源镜像）
   （把全局开源出去的快照）

• 全局 ~/.pi/agent/ 是权威源：所有项目运行时实际加载的中心，是「活」的源头。改动从这里开始。
• 本项目 pi/agent/（不带点）是开源镜像：把全局内容开源出去的快照。因目录名不是 .claude，Claude Code 不自动加载它；它纯粹用于开源。与全局逐字节一致（五部分：skills / CLAUDE.md / docs / patch / extensions；另含第六类生成式清单 pi/agent/npm/——pi 第三方包的备份与迁移）。
• 各 agent 项目的 .claude/（历史）：早期曾有「全局 → 各 agent 项目 .claude/ 副本」分发层，2026-09-13 起已终结（单一出口、副本全部清空）——各 agent 运行时同样直接加载全局 ~/.pi/agent/，不再有项目副本这一层。

权威方向单向流出：改动先在全局落地 → 同步到本项目 pi/agent/ 镜像。绝不能反过来只改镜像——那样会与权威源分叉。全局 ~/.pi/agent/docs/capability-sync.md 有完整说明。

同步范围（五部分）：skills/（通用 skill）、CLAUDE.md、docs/（拆出的参考文档：agents-registry / new-agent-scaffold / capability-sync 等）、patch/（自研辅助机制：skill-custom / session-sweep / npm-manifest / session-link / settle-repo-check 等）、extensions/（~/.pi/agent/extensions/ 下的工具强制 .ts，项目专用扩展——含项目硬编码 / 仅单项目激活——不进镜像）——这五部分在全局是权威、本项目 pi/agent/ 下同名路径是镜像，逐字节一致。不含：commands/（各处自行管理，不进同步）、项目级专属 skill（如本 capability-manager、各 agent 的 trade / vend 等专属 skill）、settings.json（全局维护，但不进开源镜像）、镜像对象目录下的本机产物（patch 的 *.log、.lock、conflicts/——不进镜像、不参与 diff）。另有第六类（生成式清单）：pi 在用第三方 npm 包的备份清单——~/.pi/agent/npm/ 的 package.json / package-lock.json + 生成的 PACKAGES.md，由 patch/npm-manifest/refresh.py 刷新到本项目 pi/agent/npm/；属生成式内容，用 --check 核验、不做逐字节 diff；装 / 删 / 升级 pi 包后自动刷新（不问用户）。

与 CLAUDE.md 的分工（为什么需要这个 skill）

全局 ~/.pi/agent/CLAUDE.md（与本项目 pi/agent/CLAUDE.md 逐字节相同）已经把规则写全了——权威方向、逐字节一致、敏感信息禁写、暂存区禁 AI 增删改、CHANGELOG 纪律……这些是 S 级、每次会话都在场的硬规矩。本 skill 不重复这些规则，而是把它们按「用户现在要做什么」重新编排成可执行的流程（步骤顺序、检查清单、命令模板）。换句话说：CLAUDE.md 管「规则与约束」，本 skill 管「按场景怎么做」。遇到规则细节，本 skill 会指向 CLAUDE.md 的具体章节，而不复述。

通用护栏（所有场景都要跑）

无论做下面哪个场景，每次都要套这一组护栏。它们大多对应 CLAUDE.md 里始终在场的硬规则，这里只列要点与命令，原因见 CLAUDE.md 对应章节。

• 先落全局、再镜像 pi/agent/：任何内容改动先在全局 ~/.pi/agent/ 改，确认无误后用 cp 覆盖到本项目 pi/agent/ 对应位置。绝不在镜像里直接改。（~/.pi/agent/docs/capability-sync.md）
• 敏感信息禁写：往任何会被 git 跟踪的文件里写内容前，先判断是否含密钥 / 账户号 / token 等；有则用占位符，真实值只写进 .gitignore 忽略的本机文件。（CLAUDE.md「敏感信息禁止写入」节）
• 暂存区禁 AI 增删改：本 skill 绝不执行 git add / git rm --cached / git reset HEAD / git mv 等任何会动暂存区的命令。改完的内容留给用户自己 git add，提交走 /commit。（CLAUDE.md「Git 暂存区禁止 AI 自主增删改」节）
• diff 验证一致性：内容改动同步到镜像后，跑 diff -r ~/.pi/agent/<部分> pi/agent/<部分> 确认逐字节一致（被 .gitignore 隔离的敏感文件是唯一允许的差异）。不一致就说明同步没做对，必须修到一致；第六类 npm 清单用 python3 ~/.pi/agent/patch/npm-manifest/refresh.py --check 核验。（capability-sync.md「怎么验证」）
• 记本项目的 CHANGELOG：每一次文件增删改都在本项目根 CHANGELOG.md 记一条，写清「为什么改 + 改了什么」。同步这件事本身也只记本项目的 CHANGELOG，不记各业务项目的。（CLAUDE.md「CHANGELOG 记录纪律」节 +「同步动作只记本项目的 CHANGELOG」）
• TODO 闭环：改完查项目根 TODO.md，若改动对应某条待办，按规则标记（✅**已完成** / ✅**已更新**）并补时间戳，不删原条目。

这组护栏是底线，下面三个场景的具体流程都默认你已经套上了它们。

场景 A：改通用能力内容

触发：新增、修改、下线某个全局 skill / CLAUDE.md / docs 参考文档。（settings.json 也归 Prometheus 维护，但只改全局、不进开源镜像。）

核心步骤：

1. 定位改什么、为什么：先确认是哪类内容（skill / rule / CLAUDE.md 元规范 / settings.json），改的触发原因是什么——这一条会写进 CHANGELOG 的「为什么改」。
2. 在全局 ~/.pi/agent/ 改：改 ~/.pi/agent/skills/、~/.pi/agent/CLAUDE.md（全局规则就在 CLAUDE.md 对应章节内；或 ~/.pi/agent/settings.json）对应文件。
   • 若是改 skill 内容（SKILL.md 正文 / description / references 结构），先读 skill-creator 方法论（~/.pi/agent/skills/skill-creator/）再动手——这是 CLAUDE.md「写 skill 内容须依据 skill-creator」的硬要求。
   • 若是新增 / 下线一整个 skill，涉及多位置联动（镜像、README 与相关文档），完整流程见 references/content-lifecycle.md。
3. 镜像到本项目（五部分：skills / CLAUDE.md / docs / patch / extensions，全部 cp 到 pi/agent/ 下同名路径；另第六类清单装 / 删 / 升级 pi 包后跑 refresh.py）。settings.json 不镜像。
4. diff 验证：diff -r 确认全局与镜像逐字节一致。
5. 记 CHANGELOG + TODO 闭环。

详见 references/content-lifecycle.md（含新增 / 下线 skill 的全链路、改 CLAUDE.md 元规范的注意点）。

场景 B：同步与一致性核对

触发：把通用能力同步到本项目镜像；或核对全局 / 镜像是否一致。

核心步骤：

1. 判断同步方向：分两种情形——
   • 全局 → 本项目 pi/agent/ 镜像（最常见）：全局改好了，同步到开源镜像。逐部分 cp 覆盖。
   • 本项目 pi/agent/ → 全局（反向对齐）：若镜像被临时直接改过、领先于全局，把镜像覆盖回全局一次性对齐，之后继续全局优先。 （历史的「全局 → 各 agent 项目副本」分发层已终结——2026-09-13 副本清空，不再有此情形。）
2. 执行同步：用 cp 覆盖目标位置（命令模板与合法差异清单见 references/sync-flow.md）。
3. diff 验证：全局 vs 本项目镜像：diff -r ~/.pi/agent/<部分> ~/Developer/CapabilityManagerAgent/pi/agent/<部分>；npm 清单（第六类）：python3 ~/.pi/agent/patch/npm-manifest/refresh.py --check。
4. 处理差异：diff 报差异 → 判断是「同步没做对」还是「合法差异」（如 backup 的 endpoints/ 等本机数据子目录，被 .gitignore 隔离）。前者修到一致，后者保留。
5. 记 CHANGELOG：同步动作只记本项目 CHANGELOG。

详见 references/sync-flow.md（含五部分与 npm 清单的同步命令、合法差异清单、一致性巡检脚本）。

场景 C：团队扩展（注册表 + 脚手架）

触发：给团队注册表新增 / 调整 agent；搭一个新 agent 项目脚手架。

核心步骤：

1. 新增 agent（定名 + 入表）：
   • 定名：按新命名规则起名——以 Agent 结尾、前缀尽可能简单（如 cuAgent；2026-10-09 修订，不再强制拟人名）；用户要求拟人名时才按历史惯例（蕴含主要能力、双关优先）。定名后先读全局 ~/.pi/agent/docs/agents-registry.md 的「智能体命名注册表」查重（拟人名与项目名都查），全局不可重复。
   • 把「名称 + 项目 + 职称 + 职责」追加进注册表（只追加新行、不改已有行），并在「销售流水线与三小组」段补位置说明。这步免确认（agents-registry.md「新建 Agent 时自动维护注册表」节）。
2. 搭新项目脚手架：从已有 agent 项目复制，再按角色改写——目录名以 Agent 结尾、前缀尽可能简单；不建 .claude/ 目录、不复制通用能力副本（单一出口）；写角色化 CLAUDE.md（+ AGENTS.md 软链）+ 双语 README（含名称 + logo + 徽章）、配 .gitignore。完整清单见 references/registry-and-scaffolding.md。
3. 本地 git init（免确认），不建远程、不 push。开源到 GitHub、提交、发版分别由用户触发（走对应流程或 /commit、/release）。
4. 注册表在全局 docs → 改全局、再镜像 pi/agent/：注册表改动先落全局 ~/.pi/agent/docs/agents-registry.md（若团队 agent 总数有变，全局 ~/.pi/agent/CLAUDE.md 的「团队结构参考」计数一并改），再 cp 覆盖本项目 pi/agent/docs/agents-registry.md（及 pi/agent/CLAUDE.md，若改了），diff 验证一致。

详见 references/registry-and-scaffolding.md（含定名查重流程、注册表追加格式、新项目脚手架逐项清单、开源到 GitHub 的步骤）。

何时激活

只要用户的意图落在下面任一场景，就激活本 skill（即便没明说「capability-manager」）：

• 「更新 / 修改某个全局 skill 或 rule」「给 xx skill 加个功能」
• 「改全局 CLAUDE.md 里某条规则」「改全局 settings.json」
• 「新增一个通用 skill」「下线 / 删除某个 skill」
• 「把 xx 同步到本项目镜像 / 同步到各 agent 项目」
• 「检查全局和镜像 / 项目副本是不是一致」「同步一下」
• 「新建一个 agent」「给团队加个成员」「起个 agent 名字」
• 「搭个新 agent 项目脚手架」

不激活的边界：单个业务项目内部的功能开发（那是各 agent 自己的职责）；VSCode 扩展补丁（归 Tinker / PatchClaudeAgent）；git 提交 / 发布（走 /commit、/release）。

汇报

每次完成一个场景后，报告：改了什么（哪些文件 / 哪个 skill / 注册表哪一行）、为什么（触发原因）、同步到了哪些位置（本项目 pi/agent/ 镜像）、diff 验证结果（一致 / 有哪些合法差异）、CHANGELOG 是否已记、是否触及 TODO 待办；若有需要用户自行 git add + /commit 的内容，明确提示（本 skill 不动暂存区、不提交）。