oh-my-codex Skills 与 Agents 膨胀审计（Bloat Audit）方法论与清理实战指南

本文基于 oh-my-codex 仓库中的 bloat-audit.md（配套 inventory.md 与 connectivity-roadmap.md）撰写。它讲解了 OmX 项目如何对 ./skills/（50 个目录条目、46 个磁盘 SKILL.md）与 ./src/agents/（36 个 Agent，含 3 个不可安装的 prompt 资产）进行一次数据驱动的全面清点与分类：每条 Skill/Agent 被确定性归类为 KEEP-AS-IS / CONSOLIDATE / STREAMLINE / DEPRECATE / AMBIGUOUS 之一，并附带证据、处置动作与移除风险。读完本文，你将掌握这套可复用的"技能与代理膨胀治理"方法论——从目录枚举、清单交叉比对、引用计数、孤儿分析，到按 PR 拆分落地删除，再到可重复运行的再审计流程，并了解其背后的真实仓库依据。

---

一、为什么需要一次 Skills + Agents 膨胀审计

OmX（Oh My codeX）在长期演进中沉淀了大量 Prompt 资产：skills/ 目录下的每个技能（SKILL.md）是对 Agent 的引导指令，src/agents/definitions.ts 中的 AGENT_DEFINITIONS 定义了一组可路由的 Agent 角色。随着版本迭代，这些表面（surface）会自然出现三类问题：

• 重复与冗余：多个 Skill 语义重叠（如四个 configure-* 通知配置技能合并进一个 configure-notifications）；
• 僵尸与墓碑：已废弃的技能只在磁盘上留下少量"请勿调用"的 stub，却仍占着目录与清单行；
• 孤儿化：status=active 的 Skill/Agent 在代码库中几乎无人引用，路由层也找不到它。

2026-05-23 生成的这份审计（分支 chore/skills-agents-bloat-audit，基于 origin/dev）正是针对这些问题的交付物：它是证据驱动的，所有分类都声称是数据（catalog 状态 + LOC + 引用计数）的确定性函数，而不是审计者的主观意见——"相同的输入下个月会得到相同的标签；异议应当对着数据解决，而不是对着措辞"（原文 § 头部 Style 说明）。

审计只读不改：承诺未修改 ./skills/、./src/agents/、./prompts/ 等任何生产表面，提交增量仅限于 docs/audit/skills-agents-bloat-audit/ 目录（见 README.md § Important caveats）。

二、审计方法论：七个枚举步骤 + 一个分类器

在动手写任何分类之前，审计先以可复现的方式收集全部输入数据（README.md § How this audit was produced）：

1. 枚举磁盘技能：find ./skills -maxdepth 2 -name 'SKILL.md'，得到 46 个在盘 SKILL.md；
2. 枚举 Agent：src/agents/definitions.ts 的 AGENT_DEFINITIONS + src/agents/policy.ts 中 NON_NATIVE_AGENT_PROMPT_ASSETS 声明的 3 个不可安装 prompt 资产（explore-harness、team-orchestrator），共 36 个；
3. 拉取权威状态：从 src/catalog/manifest.json（33 行 skills + 30 行 agents）读取 active / internal / alias / merged / deprecated 状态；
4. 逐技能统计：文件 LOC、最近提交（git log -1 --format='%cs|%s' -- skills/<name>/）、frontmatter 描述；
5. 逐技能/逐 Agent 计数引用：rg -l --no-messages -F '<name>' skills/ src/ prompts/ templates/（排除条目自身目录与自身 prompts/<name>.md）；
6. 技能→Agent 叙事耦合矩阵：每个 SKILL.md 正文中出现了哪些 Agent 名；
7. Agent→技能反向矩阵：每个 prompts/<name>.md 正文中出现了哪些技能名。

然后套用分类规则。每条记录的字段结构为：catalog（状态/规范别名/分类）→ shape（LOC/引用数/是否随包发布 shipped）→ 最近提交 → evidence（证据）→ action（动作）→ risk（移除风险 low/medium/high）→ rationale（一句话理由）。

分类标签语义（原文 § 头部）：

分类	含义
KEEP-AS-IS	活跃使用、与相邻表面干净契合，无需动作
CONSOLIDATE	与其他表面重复/冗余，合并进规范条目
STREAMLINE	有用但臃肿，裁掉样板或死分支
DEPRECATE	无处使用或被取代，宽限期后从磁盘 + 清单删除
AMBIGUOUS — NEEDS OWNER DECISION	数据无法定论，交由 owner 裁决

三、Inventory 异常（A1–A3）：删任何东西之前先解决的一致性缺口

审计把三类"目录 ↔ 清单不一致"单列为异常而非分类——它们应在任何删除 PR 落地之前解决：

A1：wiki 技能在盘但不在清单

• 证据：find ./skills -maxdepth 2 -name 'SKILL.md' 返回 skills/wiki/SKILL.md；用 Python 检查清单 python3 -c "import json; m=json.load(open('src/catalog/manifest.json')); print(['wiki' in [s['name'] for s in m['skills']]])" 输出 [False]。
• 影响：任何遍历 catalog manifest 的代码（如 omx setup 流程、doctor 检查、installable.ts）都看不到 wiki，可能不会安装它；但直接调用 $wiki 依然可用，因为 prompt 加载器按文件名解析。
• 建议决策：二选一——在 manifest 中加一行 { "name": "wiki", "category": "utility", "status": "active" }，或删除 skills/wiki/。
• Owner 默认建议：ADD 清单行（技能正文富含 43 个引用，且从文档化位置被调用）。

从当前仓库看，wiki 技能确实功能完备：skills/wiki/SKILL.md 定义了 wiki_ingest / wiki_query / wiki_lint / wiki_add / wiki_list / wiki_read / wiki_delete / wiki_refresh 操作，支持 architecture、decision、pattern、debugging、environment、session-log、reference、convention 八类页面，存储于 omx_wiki/*.md 并提供 [[page-name]] 交叉引用语法——这符合"43 引用、被多处调用"的判断，审计建议 ADD 是合理的。

A2：四个清单条目没有磁盘对应物（设计如此）

configure-discord、configure-openclaw、configure-slack、configure-telegram 全部 merged → configure-notifications。这是有意为之：configure-notifications 是规范技能，四个别名行让 omx setup 能接受旧式调用。无需动作，列出仅为防止下任 owner 误以为这是 bug。

A3：17 个在盘技能不随 plugins/oh-my-codex/skills/ 发布

其中 16 个是已废弃墓碑（ask-claude、ask-gemini、build-fix、deepsearch、ecomode、frontend-ui-ux、help、note、ralph-init、review、security-review、swarm、tdd、trace、visual-verdict、web-clone），另 1 个是 git-master（alias）。这些目录只作为墓碑存在，让 schema.test.ts 与 manifest 保持一致；不面向用户安装，唯一消费者是 lint + catalog 测试表面。宽限期过后，17 个可以一次性清扫（即路线图 PR-1）。

四、技能分类全景：50 个条目的去留

4.1 KEEP-AS-IS（16 个活跃 + 1 个 alias + 1 个 internal）

16 个活跃技能分布在三个 category：shortcut（ai-slop-cleaner 148 LOC/16 refs、analyze 146/28、ask 58/295、design 180/62、visual-ralph 161/17）、execution（autopilot 205/65、autoresearch 72/72、autoresearch-goal 36/20、performance-goal 65/18、pipeline 97/32、ralplan 187/77、ultragoal 131/68、ultraqa 254/36、ultrawork 175/46）、utility（doctor 239/34、hud 98/86）。

• git-master（alias）：27 LOC、8 refs、shipped=no，是有意为之的 shim，将 $git-master 重定向到 git-master Agent；
• worker（internal）：106 LOC、165 refs——内部技能中引用数最高，因为每个 team-runtime 测试都引用它。审计判定：内部表面专用，不暴露、不删除（commit fix: stop generating skill agents (#897)）。

4.2 STREAMLINE（可选瘦身，7 个）

"有用且连接良好，但很重"，瘦身是可选项，仅当内容相对当前契约腐化时才值得做；且都应推迟到墓碑删除 PR 之后，以便 diff 更易读：

技能	LOC	refs	备注
cancel	399	67	按负载规模合理
code-review	288	54	canonical=code-reviewer
deep-interview	490	74	规划类最重
plan	277	204	引用数极高
ralph	294	141	execution
skill	836	160	全仓库最重技能
team	520	270	引用数最高

4.3 CONSOLIDATE——已折叠（4 个）

四个 configure-* 条目在 manifest 中为 status=merged、canonical=configure-notifications，磁盘上无目录（LOC=—、ref_count=0）。清单行保留别名以支持 omx setup 查找；除非 owner 决定完全放弃公开名，否则保留清单行。

4.4 DEPRECATE（16 个墓碑）

16 个技能已被"硬弃用"：正文明确写着 "Do not invoke or route this skill"，LOC 多在 10～16 之间（个别例外：ecomode 114、tdd 104、web-clone 357）。引用计数看似不低（如 help 161、review 163、note 74、trace 41），但审计强调这些引用集中在 catalog/manifest 条目与 lint 契约测试中，而非真实消费者。风险等级据此标注：help/note/review/trace 为 medium（因引用面较大），其余为 low。

处置动作统一为：owner 确认无外部 $<name> 用户后，目录 + 清单行一次清扫（PR-1）。

4.5 AMBIGUOUS——需 owner 决策（5 个）

数据无法定论的五项，共同特征是"active 但连接度低"（refs ≤ 15），两条路：要么是代码库忘记宣传它的重要工作，要么是悄悄孤儿化：

技能	LOC	refs	建议动作
best-practice-research	83	12	确认仍在 autopilot/ralplan/team 叙事中，否则降为 internal 或并入父技能
configure-notifications	287	6	同上（注意这是 4 个 configure-* 的规范目标）
omx-setup	135	15	同上
prometheus-strict	219	11	同上（最近提交：feat(prometheus-strict): require second planning round）
wiki	57	43	NOT_IN_MANIFEST——重复 A1 异常，风险 medium

五、Agent 分类全景：36 个角色的路由去留

Agent 部分采用与技能相同的格式，但证据维度多了一项：definition 取自 src/agents/definitions.ts 的 AgentDefinition 接口——posture（frontier-orchestrator / deep-worker / fast-lane）、modelClass（frontier / standard / fast）、routingRole（leader / specialist / executor）、tools（read-only / analysis / execution / data）、category（build / review / domain / product / coordination）。3 个 NOT_IN_MANIFEST 条目即 src/agents/policy.ts 中 NON_NATIVE_AGENT_PROMPT_ASSETS 声明的非安装 prompt 资产。

5.1 KEEP-AS-IS（18 活跃 + 2 internal + 3 非安装资产）

18 个活跃 Agent（括号内为 refs）：analyst(15, 工具=analysis)、architect(111, read-only)、code-reviewer(21, read-only)、critic(56, read-only)、debugger(25, analysis)、dependency-expert(14, analysis)、designer(24, execution)、executor(114, 定义留空)、explore(99, read-only, fast-lane)、planner(35, analysis)、prometheus-strict-metis/-momus/-oracle(各 7, analysis)、researcher(33, analysis)、test-engineer(28, execution)、verifier(23, analysis)、vision(17, read-only)、writer(21, execution)。

• internal（2）：code-simplifier(11)、team-executor(9)——有意不对外路由；
• 非安装资产（3）：explore-harness(12)、sisyphus-lite(5)、team-orchestrator(2)。它们作为子 prompt 被嵌入技能（sisyphus-lite → ralph、team-orchestrator → team、explore-harness → explore），不直接安装。动作：验证消费技能仍拉取该 prompt，否则为死代码，应在后续清扫中删除（风险 medium/low）。

5.2 CONSOLIDATE（10 个已合并 Agent）

10 个 Agent 在 catalog 中为 status=merged，映射到 4 个规范目标：

规范目标	已合并条目（refs）
code-reviewer	api-reviewer(9)、performance-reviewer(13)、quality-reviewer(17)、style-reviewer(15)
designer	information-architect(7)、ux-researcher(8)
analyst	product-analyst(8)、product-manager(11)
test-engineer	qa-tester(9)
verifier	quality-strategist(6)

这些条目保留在 AGENT_DEFINITIONS + prompts/<name>.md，仅为与旧安装的 omx setup 保持升级路径对等。动作：≥1 个发布周期后移除 definitions 条目与 prompt 文件，清单行保留 merged 以维持升级路径稳定（quality-reviewer 因 refs 17 标为 medium 风险，其余 low）。

5.3 DEPRECATE（2 个）

build-fixer(5) 与 security-reviewer(5)：catalog 已标记 deprecated，refs 几乎全是 catalog/测试样板。动作：确认无技能正文仍引用后，移除 AGENT_DEFINITIONS 条目、prompts/<name>.md 及任何 policy 豁免。

5.4 AMBIGUOUS（1 个）

git-master Agent(8)：active 但连接度低。owner 需确认存在活跃消费者；否则降为 internal 或并入最近邻（注意与技能侧 git-master alias 相呼应）。

六、汇总数字：清理后的目标形状

技能（50 个 catalog 条目、46 个在盘）：

分类	数量
KEEP-AS-IS	16
KEEP-AS-IS (alias)	1
KEEP-AS-IS (internal)	1
STREAMLINE (optional)	7
CONSOLIDATE — already collapsed	4
DEPRECATE	16
AMBIGUOUS — NEEDS OWNER DECISION	5
合计	50

Agent（36 个）：

分类	数量
KEEP-AS-IS	18
KEEP-AS-IS (internal)	2
KEEP-AS-IS (non-installable asset)	3
CONSOLIDATE	10
DEPRECATE	2
AMBIGUOUS — NEEDS OWNER DECISION	1
合计	36

根据 connectivity-roadmap.md § 6，PR-1 至 PR-4 落地后表面收缩至 约 30 个在盘技能、约 21 个 Agent，零"在盘却缺清单"技能，每个活跃技能至少有一条跨技能链接（或有意位于跨链接层之下）。

七、落地路线图：PR 如何按序拆分

路线图的原则是先删墓碑、再合并、最后补连接——确保每个连接性修复都落在 catalog 的最终形态上，而不是过渡形态上；每个 PR 评审控制在 30 分钟内，全部面向 dev 分支：

• PR-1（Phase A，medium 风险）：删除 16 个 deprecated 墓碑技能目录 + 更新 manifest + 2 个 catalog 测试。前置检查：对每个名字 rg -l -F '<name>'，若源码（非测试）仍硬编码则同 PR 修复。
• PR-2（Phase A，medium 风险）：删除 10 个 merged + 2 个 deprecated Agent（共 12 个 AGENT_DEFINITIONS 条目与 12 个 prompts/*.md），manifest 行保留 merged → <canonical>。依赖 PR-1。
• PR-3（Phase B，独立）：解决 A1 异常——给 wiki 加清单行，或删 skills/wiki/ 目录（默认建议是 ADD）。
• PR-4（Phase C，docs，低风险）：应用 Q1–Q9 九个"快速连接修复"（单文件编辑、每项 <30 分钟），包括：performance-goal 的 Agent Loop 指名 executor/test-engineer；omx-setup ↔ doctor 互链；configure-notifications 底部加"webhook 失败跑 $doctor"；autopilot 指名 $ai-slop-cleaner；code-review 提交准备步指到 git-master；analyze/ralplan 链到 dependency-expert；design 链到 vision；autopilot 提一句 $prometheus-strict。依赖 PR-1、PR-2。
• PR-5..8（Phase D，owner 路由，可选）：S2 合并 prometheus-strict 三 Agent 为一个组合体；S3 将 team-executor 提升为 active；S1 两个发布周期后丢弃 configure-* merged 行；S6 将 performance-goal 折叠进 ultragoal --performance。

依赖图：PR-1 ──┐＋PR-2 ──┘ → PR-4；PR-3 独立可随时落地；PR-5..8 无固定顺序。

八、关键机制与底层依据

本审计的核心机制是 catalog manifest 作为唯一权威状态源：

• src/catalog/schema.ts 定义了 CatalogEntryStatus = 'active' | 'alias' | 'merged' | 'deprecated' | 'internal'、技能四类 execution | planning | shortcut | utility、Agent 五类 build | review | domain | product | coordination，并强制核心技能集合 {'autopilot','ralplan','team','ultragoal'}——这正是审计分类标签的合法取值来源；
• src/agents/policy.ts 的 NON_NATIVE_AGENT_PROMPT_ASSETS 定义了三类"非安装 prompt 资产"；isNativeAgentInstallableStatus 规定仅 active/internal 可直接安装；assertNativeAgentCanonicalTargets 强制 alias/merged 条目必须声明 canonical 目标且该目标可安装——从源码层面印证了"合并条目保留、规范目标必须活跃"的审计原则；
• 用 python3 -c "import json; m=json.load(open('src/catalog/manifest.json')); ..." 可复核当前清单：技能 33 行、Agent 30 行，且 wiki 已存在于 skills 清单中、git-master 存在于 agents 清单中——说明审计之后清单已随仓库演进（审计报告的 A1 反映的是 2026-05-23 的时点状态）。

从源码结构看，AGENT_DEFINITIONS 的 posture/routingRole 三元组构成了路由层区分"leader 编排 / specialist 专精 / executor 执行"的骨架，这与审计中"连接度 = 路由可达性"的视角是一致的：一个 active 但低引用的 Agent，即使 definitions 齐全，也可能因没有技能正文或相邻 Agent 指向它而无法被模型在路由时发现。

九、可复现的再审计流程

审计完全可复现（README.md § Re-running this audit）：

1. 对仓库新状态重新执行上述 7 个枚举步骤；
2. 重新套用 bloat-audit.md 头部记录的分类规则；
3. 将新 inventory.md 与已提交版本 diff，观察什么发生了变化。

由于每个分类都是 catalog 状态 + LOC + 引用计数的确定性函数，未来同一提交会得到相同标签（除非新增或删除了条目）。原始中间数据（各技能指标 CSV、引用 CSV、扁平化 catalog dump、合并 JSON）在审计期间生成于临时 notes/ 目录并有意不提交——它们可在任意提交上重新生成。

最后提醒两项硬性边界：其一，审计是"意见 + 证据"而非单方面命令，每个分类都可对照数据辩驳，删除决策由 owner 按 PR 逐一授权；其二，引用计数是上界——ask、plan、team、note、review、help 这类短英文词会因误报而虚高，分类器对结构引用（catalog、模板、CLI 表面）的权重高于散文式提及。理解这两点，你就能把同样的方法论搬到任何 Prompt 资产不断膨胀的 Agent 工程项目中。