agent-health git:20260920.81a3f42A

Immutable. This exact content never changes and is served at /api/v1/blob/5fb81ece90e1b855.

---
name: agent-health
description: 在审计 AGENTS/CLAUDE 指令、MCP、hooks、工具权限、验证入口和跨工作流配置漂移时使用；只审技能规范、打包、触发和评测时使用 skill-audit，不因普通任务涉及配置就触发。
---

# 代理配置健康检查

## 目标

找出代理工作流里会让后续执行变差的配置漂移：规则冲突、技能触发错误、钩子过宽、MCP 权限不清、验证命令失真、持久上下文过期。

## 何时使用

- 检查 `AGENTS.md`、`CLAUDE.md`、技能、钩子、MCP、代理配置
- 用户觉得 Codex/Claude 没按规则执行
- 新增或迁移一批技能后，需要确认边界是否清楚
- 长期项目里验证命令、生成物规则或上下文文档可能已经过期

如果范围只包含一个或多个 Agent Skills 的规范、打包、描述、脚本和评测，使用 `skill-audit`。`agent-health` 只在这些技能需要和更广的指令、工具、权限或运行时配置一起审查时覆盖技能路由。

## 审计层次

按下面顺序检查，先做概要检查，只有发现高风险或用户要求深入时再扩展：

1. `指令入口`：`AGENTS.md`、`CLAUDE.md`、项目 README、技能头部元数据是否冲突
2. `技能路由`：description/when_to_use 是否过宽、互相抢触发、缺少禁用边界
3. `工具与钩子`：钩子、MCP、允许使用的工具、脚本是否有过宽权限或隐式副作用
4. `验证入口`：测试、静态检查、构建、应用配置、生成物检查是否真实可运行；代理能否从启动、最小变更走到可观察结果
5. `持久上下文`：计划、交接、记忆、文档是否过期、重复或包含私有路径
6. `可维护性`：是否有重复规则、薄技能、无人维护的脚本、公共/私有边界混乱

概要检查没有发现具体冲突、失效入口或权限风险时停止，不为了“完整”遍历所有插件、历史文件和敏感目录。进入深度检查时记录触发它的证据和具体范围。

## 检查规则

- 证据优先：每个问题必须引用具体文件、命令输出或配置项
- 当前仓库状态优先于记忆和旧总结
- 不把缺少“完美治理”当问题；按项目复杂度校准
- 钩子和自动触发规则要重点看副作用、权限范围和是否可关闭
- 静态检查、编译通过或工具返回成功，不自动等于用户可观察行为正确；需要区分源码、测试、集成、运行面和人工证据
- 检查验证命令是否能快速失败、给出可执行的下一步，并且与当前仓库的实际入口、版本和生成物路径一致
- 发现敏感信息时只报告类型和路径，不复制具体值
- 无法运行真实验证入口时标记为“未验证”，不把静态存在、配置声明或旧文档当作运行成功

## 规则归属

审计或整理规则时，先判断它应该放在哪里：

- 只有跨项目长期成立、能直接执行且足够短的约定才进入全局 `AGENTS.md`
- 可复用的多步骤工作流、证据要求和领域判断放入对应 Skill
- 稳定的命令序列和机械检查优先固化为脚本，项目事实和本地约束留在项目文档或项目级规则中
- 一次性偏好和当前任务决定留在会话中，不为它们增加永久规则
- 同一规则只保留一个权威来源；其他位置如需提及，只保留触发或导航信息

## 输出格式

- 按严重度列出问题；每项包含文件或配置、证据、影响和处理建议。
- 正常区域只在有助于说明检查覆盖面时简要列出。
- 未验证区域和残余风险仅在实际存在时报告，不输出空章节或占位内容。

## 严重度

- `P0`：会泄露敏感信息、自动执行破坏性动作、错误发布/提交/部署
- `P1`：会持续误导代理，例如错误验证命令、过宽触发、冲突规则、失效钩子
- `P2`：维护成本或清晰度问题，例如重复规则、过期文档、低价值技能