---
name: skill-audit
description: >
  当用户要求梳理、审计、评估或优化某个 skill 时使用。
  对目标 skill 进行多维度分析，输出结构化审计报告和改进建议。
  触发短语：梳理 skill、审计技能、检查 skill、优化 skill、
  看看这个 skill 有没有问题、帮我 review 这个 skill、这个 skill 合理吗、
  评估 skill 是否适合项目、skill review、audit skill、improve skill。
---

# 技能审计技能

## 定位

对指定 skill 进行系统化审计，核心目标是评估 **skill 是否有效地指导 agent 完成任务**，
而不是字数或格式治理。输出结构化报告和可操作的改进建议。

## 审计优先级

按以下顺序评估，高优先级问题未解决时，低优先级问题仅做标记不深入：

1. **项目硬规则合规** — 违反即阻断
2. **skill 有效性** — 能否真正指导 agent 完成任务
3. **结构与触发** — 结构合理性和触发可靠性
4. **业界对标** — 可借鉴的外部实践

## 项目硬规则（违反即 Fail）

规则优先级：`docs/` > `AGENTS.md` / `CLAUDE.md` > skill 自身。当 skill 与 `docs/` 或入口文件冲突时，以更高优先级为准，skill 必须修正。

- `.agents/skills/` 是唯一维护源，分发目录不手动修改
- 修改后必须可通过 `npm run sync:skills` 同步
- 输出语言为中文，description 包含中英文触发词
- `docs/` 是事实源，skill 不替代文档，不重复定义规则
- skill 引用的文件路径必须真实存在
- skill 中的规则不得与 `AGENTS.md` / `CLAUDE.md` 矛盾（如分支保护、测试策略等）
- 新增/删除 skill 必须同步更新 `.agents/skills/README.md`

## 工作流

### 1. 确定审计目标

- 确认要审计的 skill 名称和路径（`.agents/skills/{name}/`）
- 读取目标 SKILL.md 和所有 references/ 文件
- 读取 `.agents/skills/README.md` 了解 skill 在全局中的定位

### 2. 五维度分析

每个维度独立评分（Pass / Needs Improvement / Fail）：

#### D1: 项目硬规则合规

逐项检查"项目硬规则"章节中的每一条。任何一条不通过即 Fail。

#### D2: 有效性与内容质量

这是审计的核心——skill 的内容是否真正帮助 agent 做对事情。

- skill 是否包含项目特有的 **gotchas**（反直觉事实）——这是最高价值内容
- 规则是否可验证、无歧义，而不是空泛的原则声明
- 是否在教 agent 已知的基础知识（应删除）
- 输出格式是否用模板定义（比散文描述有效）
- 工作流是否有验证闭环（执行→验证→修复）
- 规则和禁止事项的数量是否合理（经验参考：核心规则 ~5-7 条、禁止事项 ~3-5 条；但数量本身不是目标，每条规则是否有实际指导价值才是关键）

#### D3: 结构与触发可靠性

- frontmatter 是否完整：`name` + `description`（含中英文触发短语）
- SKILL.md 是否有清晰分节（经验参考：≤150 行理想，但不是硬限——内容密度比行数重要）
- references/ 文件是否都被 SKILL.md 引用，有无孤立文件
- 和其他 skill 是否存在职责重叠
- 是否存在"万能 skill"倾向

#### D4: 项目适配性

- skill 的规则是否反映当前项目实际的技术栈和架构
- references/ 中的模板和检查项是否和 `docs/` 中的事实源一致
- 控制粒度是否匹配任务脆弱性

#### D5: 业界最佳实践对标

- 在互联网上搜索该 skill 所属领域的 AI agent 最佳实践
- 参照 `references/official-best-practices.md` 中的官方检查项对标
- 对比当前实现与业界方案，识别可借鉴的思路

### 3. 输出审计报告

按 `references/audit-report-template.md` 模板输出。发现必须分级：

1. **阻断项（Fail）** — 违反项目硬规则，必须修复才能使用
2. **高优先级优化** — 明显降低 skill 有效性的问题
3. **低优先级优化** — 可改进但不影响基本功能

输出时严格按此顺序排列，先阻断再优化。

## 核心规则

1. **先读完再评** — 读完 SKILL.md 和所有 references 才能开始分析
2. **有效性优先** — 评估 skill 是否真正帮 agent 做对事，不是数行数
3. **有据可查** — 每个发现必须引用具体行号或文件路径
4. **搜索验证** — D5 必须实际搜索互联网，不能凭记忆编造最佳实践
5. **可操作** — 改进建议必须具体到"改哪里、改成什么"，不给空泛建议