# Capability Manager

> 维护智能体团队的通用能力底座，是 Prometheus（通用能力管家）的操作手册。覆盖全局 ~/.pi/agent/ 下 skills / CLAUDE.md / docs / patch / extensions 五部分及 pi 第三方包清单（第六类，生成式）的增删改，全局权威源 ~/.pi/agent/ ↔ 本项目开源镜像 pi/agent/ 的同步与一致性核对（单一出口，各 agent 项目不再分发副本），以及团队智能体注册表维护与新 agent 项目脚手架。当用户要求：新增 / 修改 / 下线某个全局 skill、改全局 CLAUDE.md 或 docs 参考文档或 settings.json、把某个通用能力同步到本项目镜像、核对全局与镜像是否一致（diff）、给团队注册表新增或调整 agent、搭新 agent 项目脚手架，或任何涉及「~/.claude 通用能力维护 / 镜像同步 / 团队注册表」的工作时，都必须用本 skill——即便用户没明说「capability-manager」，只要意图落在上述场景即触发。触发后按对应场景执行流程、跑通用护栏（全局权威优先落地、敏感信息禁写、暂存区禁 AI 增删改、diff 验证逐字节一致、记本项目 CHANGELOG）。

- Skill: `xhqing/capability-manager-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add xhqing/capability-manager-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xhqing/capability-manager-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xhqing (https://skillmd.com/u/xhqing)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/xhqing/capability-manager-2

---


# 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`](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`](references/content-lifecycle.md)（含新增 / 下线 skill 的全链路、改 CLAUDE.md 元规范的注意点）。

---

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

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

**核心步骤**：

1. **判断同步方向**：分两种情形——
   - **全局 → 本项目 `pi/agent/` 镜像**（最常见）：全局改好了，同步到开源镜像。逐部分 `cp` 覆盖。
   - **本项目 `pi/agent/` → 全局**（反向对齐）：若镜像被临时直接改过、领先于全局，把镜像覆盖回全局一次性对齐，之后继续全局优先。
   （历史的「全局 → 各 agent 项目副本」分发层已终结——2026-09-13 副本清空，不再有此情形。）
2. **执行同步**：用 `cp` 覆盖目标位置（命令模板与合法差异清单见 [`references/sync-flow.md`](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`](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`](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`](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 不动暂存区、不提交）。

