# Audit Skill Design

> 审查已有或正在编写的 Codex/Claude Code Skill 的设计质量、问题边界和可复用性，并提出可执行修订建议。当用户要求审查、评估、改进、精简、拆分或合并 Skill、SKILL.md、Skill 文件夹、Skill 触发描述或工作流时使用；尤其适用于判断 Skill 是否过宽、过窄、职责混杂、触发不准、缺少 Gotchas、验证不足或渐进披露不合理。不要用它代替领域产出质量审查，也不要在用户仅要求从案例创建新 Skill 时单独使用。

- Skill: `arcdodo/audit-skill-design` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add arcdodo/audit-skill-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arcdodo/audit-skill-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: arcdodo (https://skillmd.com/u/arcdodo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arcdodo/audit-skill-design

---


# Audit Skill Design

审查一个 Skill 是否形成了清晰、稳定、可验证的最小复用单元，并给出能够直接实施的修订方案。

## 核心判断

不要按描述是否具体、是否聚焦到行业来判断边界。判断一组任务是否适合属于同一 Skill，检查它们能否共享：

1. **输入契约**：运行前需要收集的信息、文件和配置基本一致。
2. **核心流程**：主要阶段、工具和决策逻辑基本一致。
3. **Gotchas**：模型默认容易做错的事情和隐性知识基本一致。
4. **验收标准**：能够使用同一套方法判断任务真正完成。
5. **风险等级**：权限、确认要求和不可逆操作的风险相近。

将满足以上条件的一组任务视为一个 Skill。把每次变化的内容保留为任务参数，不要据此拆分 Skill。

## 审查流程

### 1. 建立审查证据

读取目标 Skill 的：

- `SKILL.md`
- 从 `SKILL.md` 直接链接的 references
- 实际使用的 scripts、templates、assets 和 agents metadata
- 用户提供的真实请求、失败案例或运行结果

不要仅凭文件名或 description 下结论。缺少运行证据时，明确标注哪些判断仅基于静态审查。

从 description、工作流、示例和真实请求中列出所有可证实的代表性任务变体，通常选择 3 至 7 个。后续边界判断必须比较这些变体；如果材料只支持很少变体，仍可审查触发、流程和验证设计，但应降低拆分或合并结论的置信度。

### 2. 定义 Skill 声称解决的问题

用一句话重写目标 Skill：

> 当用户需要在 `<使用场景>` 下，针对 `<任务对象>`，完成 `<结果>` 时使用；通过 `<验收方式>` 确认完成。

如果无法准确重写，优先判断其边界或完成标准不清晰。

### 3. 审查问题边界

使用“五同测试”检查输入、流程、Gotchas、验收和风险。详细判定标准见 [`references/AUDIT-RUBRIC.md`](references/AUDIT-RUBRIC.md)。

区分：

- **范围过宽**：包含无法共享核心工作流或验收标准的任务。
- **范围合适**：形成独立、稳定、可验证的最小复用单元。
- **范围过窄**：边界主要由一次性参数定义，缺乏重复使用价值。

提出拆分建议时，必须指出具体在哪些维度发生分歧。不要仅因为存在多个行业、工具或输出类型就建议拆分。

### 4. 审查 Skill 设计

按优先级检查：

1. description 是否能准确触发并排除相邻任务。
2. 是否沉淀了非显而易见的 Gotchas，而非重复通用知识。
3. 是否定义了真实完成条件，并防止“看似完成”的错觉。
4. 自由度是否与任务风险匹配。
5. `SKILL.md` 是否只保留核心流程和路由。
6. references、scripts、templates、assets 是否必要且可被发现。
7. 是否存在重复、矛盾、失效链接或无用途文件。
8. 冷启动 agent 是否能在没有隐藏上下文时执行。

严重程度必须依据缺陷造成的实际失败概率和影响，不依据违反了多少检查项。不要把缺少某种推荐目录、格式或写法本身视为缺陷。

### 5. 输出审查报告

使用 [`references/REPORT-FORMAT.md`](references/REPORT-FORMAT.md) 的结构。

要求：

- 发现项优先，按严重程度排序。
- 每项发现引用具体文件和位置，并说明实际影响。
- 区分“必须修复”“建议改进”和“证据不足”。
- 给出最小可行修订，不要默认重写整个 Skill。
- 没有问题时明确说明，并列出剩余风险或测试缺口。

### 6. 自审与验证

完成审查后，检查自己的报告：

- 是否把偏好误写成缺陷？
- 是否有证据支持每个重要结论？
- 拆分建议是否通过五同测试？
- 是否给出了可实施的修订，而非抽象评价？
- 是否审查了真实完成条件，而不只审查文档形式？

如果用户要求修改目标 Skill，在报告完成后实施修订，并重新审查修改结果。