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 维护,但只改全局、不进开源镜像。)
核心步骤:
- 定位改什么、为什么:先确认是哪类内容(skill / rule / CLAUDE.md 元规范 / settings.json),改的触发原因是什么——这一条会写进 CHANGELOG 的「为什么改」。
- 在全局
~/.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。
- 若是改 skill 内容(SKILL.md 正文 / description / references 结构),先读 skill-creator 方法论(
- 镜像到本项目(五部分:skills / CLAUDE.md / docs / patch / extensions,全部
cp到pi/agent/下同名路径;另第六类清单装 / 删 / 升级 pi 包后跑refresh.py)。settings.json 不镜像。 - diff 验证:
diff -r确认全局与镜像逐字节一致。 - 记 CHANGELOG + TODO 闭环。
详见 references/content-lifecycle.md(含新增 / 下线 skill 的全链路、改 CLAUDE.md 元规范的注意点)。
场景 B:同步与一致性核对
触发:把通用能力同步到本项目镜像;或核对全局 / 镜像是否一致。
核心步骤:
- 判断同步方向:分两种情形——
- 全局 → 本项目
pi/agent/镜像(最常见):全局改好了,同步到开源镜像。逐部分cp覆盖。 - 本项目
pi/agent/→ 全局(反向对齐):若镜像被临时直接改过、领先于全局,把镜像覆盖回全局一次性对齐,之后继续全局优先。 (历史的「全局 → 各 agent 项目副本」分发层已终结——2026-09-13 副本清空,不再有此情形。)
- 全局 → 本项目
- 执行同步:用
cp覆盖目标位置(命令模板与合法差异清单见references/sync-flow.md)。 - diff 验证:全局 vs 本项目镜像:
diff -r ~/.pi/agent/<部分> ~/Developer/CapabilityManagerAgent/pi/agent/<部分>;npm 清单(第六类):python3 ~/.pi/agent/patch/npm-manifest/refresh.py --check。 - 处理差异:diff 报差异 → 判断是「同步没做对」还是「合法差异」(如 backup 的
endpoints/等本机数据子目录,被.gitignore隔离)。前者修到一致,后者保留。 - 记 CHANGELOG:同步动作只记本项目 CHANGELOG。
详见 references/sync-flow.md(含五部分与 npm 清单的同步命令、合法差异清单、一致性巡检脚本)。
场景 C:团队扩展(注册表 + 脚手架)
触发:给团队注册表新增 / 调整 agent;搭一个新 agent 项目脚手架。
核心步骤:
- 新增 agent(定名 + 入表):
- 定名:按新命名规则起名——以
Agent结尾、前缀尽可能简单(如cuAgent;2026-10-09 修订,不再强制拟人名);用户要求拟人名时才按历史惯例(蕴含主要能力、双关优先)。定名后先读全局~/.pi/agent/docs/agents-registry.md的「智能体命名注册表」查重(拟人名与项目名都查),全局不可重复。 - 把「名称 + 项目 + 职称 + 职责」追加进注册表(只追加新行、不改已有行),并在「销售流水线与三小组」段补位置说明。这步免确认(
agents-registry.md「新建 Agent 时自动维护注册表」节)。
- 定名:按新命名规则起名——以
- 搭新项目脚手架:从已有 agent 项目复制,再按角色改写——目录名以
Agent结尾、前缀尽可能简单;不建.claude/目录、不复制通用能力副本(单一出口);写角色化 CLAUDE.md(+AGENTS.md软链)+ 双语 README(含名称 + logo + 徽章)、配.gitignore。完整清单见references/registry-and-scaffolding.md。 - 本地
git init(免确认),不建远程、不 push。开源到 GitHub、提交、发版分别由用户触发(走对应流程或/commit、/release)。 - 注册表在全局 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 不动暂存区、不提交)。