---
name: skill-description-audit
description: >-
  Skill Description Audit. User-level personal skill (canonical source in
  agent-skills). Cross-validation audit of an Agent Skill's SKILL.md description vs body:
  frontmatter compliance, capability claims matching the body, body non-emptiness (except
  thin-allowlist), trigger-word sufficiency, old-name residue via renames.yaml
  (boundary-aware, meta-mention filtered), H1 extraction that skips fenced code, and
  volatile-data externalization. Generates Problems/Recommendations/Acceptance-Criteria
  report in the target skill directory. Does not modify the audited SKILL.md. Use when
  auditing or cross-validating a skill description against SKILL.md body. NOT for:
  auditing product doc sets (PRDs/specs/launch docs) — use product-doc-audit.
metadata:
  version: "1.5.0"
  standard: agentskills.io
  scope: user
  patches:
    - "报告含问题/建议/验收标准三节"
    - "允许无问题、无改写建议（写「无」/维持现状）；禁止编造"
    - "description 标明：用户级个人技能；真源仍存 agent-skills"
    - "v1.2.0：新增数据外置检查维度（易变数据分层——正文不写死指向性数据，按稳定性定刷新频率）"
    - "v1.3.0：正文非空硬项（thin-allowlist 例外）；旧名检查读 renames.yaml"
    - "v1.3.1：description 显式写入 renames.yaml 旧名检查 + NOT for product-doc-audit"
    - "v1.3.2：旧名检查边界匹配 + 元提及误报过滤（复合 slug / 审计反例行）"
    - "v1.3.3：正文能力抽取跳过 fenced code（`#` 注释不当 H1）；示例主机用占位符不计本机硬编码"
    - "v1.4.0：语言一致性标准提高——description 含中文/CJK（中英混杂或中文残留，含格式示例/头部标签）由 [低] 升 **[中]**（库规范纯英文，CJK 扫描实证）；中文原生技能例外：纯中文可，禁中英混杂（2026-08-05 project-handoff/intake 教训）"
    - "v1.5.0：新增 description pushy 质量维度（§6.5）——WHEN 场景密度 + 触发关键词覆盖：正文标志性能力必须在 description 可找到触发词（否则 [中]）；WHEN 泛泛（when needed/必要时）或场景/关键词过疏 → [低] 建议补场景示例；与 skill-eval（行为评估）衔接——本维度评估触发有效性，行为验证归 skill-eval"
---

# 技能描述交叉验证审计（Skill Description Audit）

**范围：** 用户级个人技能（正文以安装位置的 `SKILL.md` 为权威；消费侧通过符号链接指向真源目录，遵循技能库「派生只链不拷」约定）。

## 角色

你是 Agent Skills 描述审计员。只审目标技能的 `SKILL.md`（尤其 frontmatter `description`），对照正文做交叉验证，并写出审计报告。

## 硬约束（不可妥协）

1. **只读目标技能** —— 禁止修改被审 `SKILL.md`（含 `description`、`name`、`metadata`、正文）。
2. **审计范围仅 `SKILL.md`** —— 不审 `scripts/`、参考文档、示例文件（除非 `SKILL.md` 用一级链接声明能力且描述声称会用到；此时仅核对「描述是否夸大」，仍不改任何文件）。**例外：数据外置检查（§5）** —— 仅查看 `references/` 目录的**存在性与表头**（lastUpdated / refreshInterval / 置信度列），不审表内容细节。
3. **唯一写出口** —— 仅在被审 `SKILL.md` **同目录** 写入/覆盖报告文件（默认名见下）。
4. **建议可写、改动不落地** —— 推荐 `description` 文案只写在报告「建议」节；不得写回 `SKILL.md`。
5. **报告结构** —— 落盘报告须含 **问题**、**建议**、**验收标准** 三节（节标题保留）。**允许无问题、无改写建议**：问题写「无」，建议写「无需改动 / 维持现状」即可；禁止为凑内容编造缺陷或强行改写文案。

## 何时使用

用户要对某个技能做描述审计、交叉验证、合规检查，或问「description 是否覆盖正文强制能力 / 触发词够不够」时激活。

## 输入

- 目标：技能目录路径，或该目录下的 `SKILL.md` 路径。
- 若未指定：询问；若工作区只有一个候选技能且用户语境明确，可对该技能执行并在报告头注明假设。
- **禁止**对本审计技能自身做「为通过审计而改描述」的循环修改；若用户要求自审，只出报告。

## 报告文件

| 项 | 规则 |
|----|------|
| 路径 | `<被审技能目录>/DESCRIPTION-AUDIT.md` |
| 已存在 | **覆盖**写入（报告头写明审计日期与对象路径） |
| 其他名 | 仅当用户显式指定文件名时改用指定名（仍须同目录） |

## 工作流

```
进度：
- [ ] 1. 定位并只读打开目标 SKILL.md
- [ ] 2. 解析 frontmatter（name / description / metadata）
- [ ] 3. 规范合规检查（含正文非空 / thin-allowlist）
- [ ] 4. 从正文抽取能力与强制点清单
- [ ] 5. 数据外置检查（易变数据分层）
- [ ] 6. description ↔ 正文交叉验证
- [ ] 7. 触发词 / 误触发风险评估
- [ ] 8. 写入 DESCRIPTION-AUDIT.md（强制：问题+建议+验收标准；不改 SKILL.md）
- [ ] 9. 向用户摘要结论 + 报告路径
```

### 1. 定位目标

解析真实路径（跟随符号链接到真源亦可）。确认存在 `SKILL.md`。记录：绝对路径、目录名、`name` 字段。

### 2. 解析 description

- 支持单行字符串与 YAML `>` / `|` 折叠标量。
- 度量 **折叠后字符数**（空白折叠为单空格后的长度）是否 ≤ **1024**。
- 拆分 **WHAT**（做什么/能力）与 **WHEN**（何时用 / `Use when`）。

### 3. 规范合规检查

依据 Agent Skills / Cursor skill 描述惯例：

| 检查项 | 通过条件 |
|--------|----------|
| 非空 | `description` 存在且去空白后非空 |
| 长度 | 折叠后 ≤ 1024 |
| WHAT + WHEN | 同时有能力说明与触发场景（中或英） |
| 第三人称 | 不以「我/你能」口吻写描述 |
| `name` | ≤64；`[a-z0-9-]+`；与目录名一致（不一致标 ⚠️） |
| YAML | frontmatter 可解析；`description` 折叠合法 |
| **结构** | frontmatter **闭合**（`---` 闭合存在）；description 折叠块**不吞正文**（描述到正文前结束——曾批量中招，防再次发生） |
| **语言一致性** | description **纯英文**（本库规范：英文——CJK 扫描零残留）；不夹「中文触发：」类双语标记；**中文原生技能例外**：正文全中文、面向中文用户的技能可用纯中文（语言统一即可），但**禁止中英混杂**（如「中文名 (English Name):」头部） |
| **正文非空** | 第二个 `---` 之后正文长度 > 0；例外仅 `thin-allowlist.txt`（如 `grill-me`）。空正文 → **[高]**（不可执行） |

缺 WHAT 或 WHEN → 至少 **[中]**。超长或空 → **[高]**。结构未闭合/吞正文 → **[高]**。**语言一致性：description 含中文/CJK（中英混杂或中文残留，含格式示例/头部标签）→ [中]**（与库规范「英文」不符——2026-08-05 教训：project-handoff 中文示例「一句话标题」/ project-intake 头部「项目对接」曾被误判 [低] 放过、未触发修正）；中文原生技能纯中文 → ✅（语言统一即可）。

### 3.5 名称语义检查（防误触发与语义漂移）

审计时顺带评估 `name` 的**语义质量**（不改名——改名是用户决策，审计只报告）：

| 检查项 | 判定 |
|--------|------|
| 单段泛名（`animation`/`research`/`launch` 类——语义指向弱、匹配易误触发）| ⚠️ **[低]** 建议改名或 description 加限定 |
| 工具/个人绑定名（`deepcode-*`/`cursor-*`/用户名）| ⚠️ **[中]** 建议去绑定（跨工具通用） |
| 引用已改名旧名（description **或正文**出现已更名的技能名——正文层是 description 审计盲区，改名后必须补查）| ⚠️ **[中]** 建议更新为新名 |

**旧名残留匹配（读 `renames.yaml`，防误报）：**

1. **只认技能引用形**：精确反引号 slug `` `old` ``；路径段 `(?<![A-Za-z0-9_-])old/SKILL` 或 `../old/`；`skill(s) old`；Markdown 链 `[old](`。  
2. **禁止子串命中**：`company-delegated-research/SKILL`、`product-launch` 等复合 slug **不**算旧名残留（勿把复合段里的 `research`/`launch` 当独立技能引用）。  
3. **元提及过滤**：同行含「单段泛名 / 旧名 / renames.yaml / 已改名 / 语义指向弱 / 旧名残留 / 禁止子串 / 复合 slug / 反例 / 误报」等审计说明语 → **不计**残留（本技能表内反例行与本条规则说明属此类）。  
4. 仅当存在至少一处**非元提及**的真实引用 → 报 **[中]**。

### 4. 正文能力清单（审计员抽取）

从正文归纳「描述应否覆盖」的条目，优先：

**抽取前先剥离 fenced code**（` ``` `…` ``` `）：围栏内行首 `# …` 是注释/示例，**不得**当作 Markdown H1/标志性能力（曾误报 `config-scan`/`secrets-scan`/`cicd-pipeline` 等）。

1. **标题/角色/何时使用** 中的核心任务（仅围栏外 `#` / 首个技能标题）  
2. **不可妥协原则 / 强制 / 必须交付**  
3. **工作流步骤名** 与关键产出物  
4. `metadata.patches`（若有）中的标志性约束  
5. **反模式** 里暗示的差异化能力（可选触发）

每条标记优先级：

- **标志性**：无此则不像本技能（缺 → 倾向 **[高]**）  
- **重要**：强制交付或专节（缺 → **[中]** 或弱覆盖 **[低]**）  
- **细节**：表格字段、实现微规则（描述省略通常 **可接受**）

### 5. 数据外置检查（易变数据分层）

检查「稳定方法论 vs 易变数据」分层是否合理——防止正文/描述写死指向性数据（会过期、造成双源）：

| 检查项 | 通过条件 |
|--------|----------|
| 识别易变数据 | 扫描正文：模型窗口/价格/API 端点与 ID/版本号/外部工具行为/统计数字等**指向性数据**；示例主机须用 `$BASE_URL` / `http://<app-host>:<port>` 等占位符——裸 `localhost`/`127.0.0.1` 计指向性 |
| 外置状态 | 该类数据应外置 `references/` 表（每表含 `lastUpdated` + `refreshInterval` + 置信度列）；SKILL.md 仅「查表」引用 |
| 刷新频率 | `refreshInterval` **按数据稳定性定**（快变 30 天 / 中变 60 天 / 慢变 90-180 天），不一律一刀切 |
| 防双源 | 正文示例不写死具体数值（写死 → 建议改查表引用）；description 不含易变数值 |

判定：
- 正文写死**快变**易变数据且未外置 → **[中]**（会过期误导）；慢变 → **[低]**
- 已外置且机制完整（lastUpdated + refreshInterval + 置信度）→ ✅
- 已外置但 `refreshInterval` 一刀切（未按稳定性）→ ⚠️ **[低]**

### 6. 交叉验证矩阵

对每条能力判定：

| 判定 | 含义 |
|------|------|
| ✅ | 描述已覆盖（允许同义：如 VO↔值对象） |
| ⚠️ | 弱覆盖或仅间接触发 |
| ❌ | 描述缺失或与正文矛盾 |
| 可接受省略 | 战术细节，不要求写入 description |

另检 **假称**：描述出现、正文无对应 → **[中]** 或 **[高]**（视是否核心）。

**合理扩展触发**（如正文写「读写分离」、描述触发词含 `CQRS`）可 ✅，须在矩阵注明「正文未用该词，作触发扩展」。

### 6. 触发词与误触发

- WHEN 是否包含用户口头常见说法与英文等价（若技能面向双语环境）。  
- 是否过宽（易误激活）或过窄（标志性能力无触发词）。  
- 双语重复：不默认判缺陷；可标 **[低]/token** 信息项。

**误触发防护（2026-08 加入——deep-codebase-analysis 被「审计技能」类请求误命中 3 次的教训）：**

- **WHEN 过宽**：description 含泛动词+泛领域组合（如 `analyzing source code` + `maintenance/refactoring`）会命中不相关请求 → 建议**收窄 Use when**（明确「分析什么、何时用」）+ 加**反触发**（`NOT for` / `DO NOT TRIGGER when`——指向该用哪个替代技能）。判定：WHEN 过宽缺反触发 → **[中]**（实测误命中）或 **[低]**（潜在风险）。
- 反触发格式示例：`NOT for: single-file edits, auditing one skill's SKILL.md — those belong to code-review / skill-description-audit.`

### 6.5 description pushy 质量（场景/关键词密度——v1.5.0）

评估 WHEN 的「可触发强度」——描述写得合规（WHAT+WHEN 齐全）不等于会被正确触发：

| 检查项 | 通过条件 | 判定 |
|--------|----------|------|
| **标志性能力有触发词** | 正文每条标志性能力（§4 抽取）都能在 description 找到对应触发词（用户可能的口头说法）| 缺 → **[中]**（标志性能力无触发词 = 该能力永远不被触发） |
| **场景密度** | WHEN 含 ≥2 个具体使用场景/触发时刻（「何时/什么情况下用」），非泛泛「when needed/必要时」| 泛泛或只有 1 个场景 → **[低]**（建议补场景示例） |
| **关键词覆盖** | 高频触发词（技能领域专有名词/常见短语）已在 WHEN | 高频词缺失 → **[低]** |
| **反触发完整** | 易误触发技能（泛动词+泛领域组合）已有 NOT for 指向替代技能（见 §6）| 缺 → **[中]**（实测误命中）或 **[低]**（潜在） |

**与 skill-eval 的分工**：本维度是静态评估——「触发词写没写、够不够」；触发后行为是否真的正确（pass-rate）归 `skill-eval`（动态行为评估）。审计建议可写「若触发仍不理想，走 skill-eval 行为验证」。

### 7. 写报告（唯一产出）

用下方模板写入 `DESCRIPTION-AUDIT.md`。语言与用户一致（默认中文）。

**三节写法：**

| 节 | 要求 |
|----|------|
| **问题** | 按严重度列出发现（含 **[信息]** 若有）。**无缺陷写「无」——合法，勿虚构。** 有条目时含：现象、证据、影响。 |
| **建议** | **无问题或描述已达标 → 写「无需改动 / 维持现状」+ 一句理由即可，不必给推荐 YAML。** 仅当确有改写价值时：给可粘贴 `description`、约计字符数、改进要点，并回指问题编号；声明未应用到 `SKILL.md`。 |
| **验收标准** | 可勾选清单，写清「何种状态算通过」。无问题/无建议时，列出**当前描述已满足**的回归项即可。禁止空泛「更好即可」。 |

### 8. 回复用户

2–4 句：总评、问题/建议/验收是否已写入报告、报告绝对路径。不把整份报告贴进聊天除非用户要求。

## 报告模板

下列为报告正文结构（落盘时勿包一层多余的外层 fence）。推荐文案用缩进代码块写出即可：

~~~
# 审计报告：<skill-name> 技能描述

- 审计对象：`<绝对路径>/SKILL.md`（frontmatter `description`）
- 审计日期：YYYY-MM-DD
- 审计方式：description ↔ SKILL.md 正文交叉验证 + Agent Skills 描述合规检查
- 结论：<一句话总评；含是否严重误导 / 是否建议改描述>

---

## 一、规范合规检查

| 检查项 | 结果 |
|--------|------|
| 描述非空 | ✅/❌ |
| 长度（折叠后） | ✅/❌ N 字符 ≤ 1024 |
| 结构（WHAT + WHEN） | ✅/⚠️/❌ |
| 第三人称 | ✅/⚠️ |
| YAML / name 与目录 | ✅/⚠️/❌ |
| 正文非空（或 thin-allowlist）| ✅/❌ |

## 二、数据外置检查（易变数据分层）

| 检查项 | 结果 |
|--------|------|
| 易变数据识别（模型窗口/价格/API ID/版本/统计）| ✅ 无 / ⚠️ 有（见问题）/ ❌ 漏检 |
| 外置状态（references/ 表：lastUpdated + refreshInterval + 置信度）| ✅ 完整 / ⚠️ 缺项 / ❌ 未外置 |
| 刷新频率按稳定性（快变 30 / 中变 60 / 慢变 90-180）| ✅ / ⚠️ 一刀切 |
| 防双源（正文/描述不写死数值）| ✅ / ⚠️ 示例写死 |

## 三、description 与正文交叉验证

| 正文能力 | 优先级 | 描述覆盖 | 判定 |
|----------|--------|----------|------|
| … | 标志性/重要/细节 | 「…」或未提及 | ✅/⚠️/❌/可接受省略 |

## 三、问题

1. **[高/中/低/信息]** <标题>
   - 现象：…
   - 证据：…
   - 影响：…
2. …

（无缺陷则本节正文为「无」。）

## 四、建议

（可「无需改动」。未应用到 SKILL.md。）

- 对应问题：#1 / #2 / … **或**「无问题，无需改动」
- 行动：维持现状 / 改写 description / 仅补触发词…
- 推荐文案：（仅行动为改写时填写；否则写「无」）

        description: >
          …

- 改进要点：（无则写「无」）
- 约计折叠字符数：（无改写则写「不适用」）

## 五、验收标准

（无问题/无建议时，用下列项确认「当前已通过」即可。）

- [ ] 折叠后 description ≤ 1024 且非空；含 WHAT + WHEN
- [ ] 无假称：描述中的能力均可在正文找到对应（含同义）
- [ ] 正文标志性强制能力均已进入 WHAT 或 WHEN
- [ ] 重要输入词/术语与正文一致（无正文不存在的输入类型）
- [ ] WHEN 含标志性触发词（含必要英文等价，若适用）
- [ ] 数据外置：易变数据已外置 references/ 表（或确认无该类数据）；refreshInterval 按稳定性
- [ ] （仅有问题时追加）针对 #N：<可勾选的通过条件>
- [ ] （仅有改写建议时追加）采纳文案后字符数 ≤ 1024，且矩阵 ❌/高中项清零

## 六、备注

- 本次审计**未修改** `SKILL.md`。
- 报告含强制节：问题、建议、验收标准。
- 报告路径：`…/DESCRIPTION-AUDIT.md`
~~~

## 严重度定义

| 级 | 标准 |
|----|------|
| **高** | 空/超长描述；**frontmatter 未闭合 / description 吞正文（结构破坏）**；标志性强制能力缺失；描述与正文核心矛盾；严重假称 |
| **中** | 缺 WHAT 或 WHEN；重要能力缺失；输入/术语与正文明显不一致；正文写死**快变**易变数据未外置；**WHEN 过宽已致误命中（缺反触发）**；**引用已改名旧名**；名称含工具/个人绑定；**description 含中文/CJK（中英混杂或中文残留——库规范纯英文，2026-08-05 提高）** |
| **低** | 触发词可补强；弱覆盖；双语重复；**单段泛名（匹配指向弱）**；WHEN 过宽仅潜在风险；细节未写入描述；慢变数据未外置；refreshInterval 一刀切 |
| **信息** | 版本未 bump、旧报告过期、合理扩展触发等非缺陷备忘 |

## 反模式

- 改写并保存被审 `SKILL.md`「顺便修好」  
- 把脚本/参考文档当作审计范围主证据而忽略 `SKILL.md`  
- 要求 description 复述全部战术细节  
- 无矩阵、无严重度、只有空泛「看起来不错」  
- 报告缺 **问题 / 建议 / 验收标准** 节标题  
- 无缺陷却编造问题，或无改写价值却硬给推荐 YAML  
- 「建议」只写「见上文」却既不维持现状也不给行动；「验收标准」写「更好即可」而无勾选项  
- 报告写到其他目录或聊天里了事（除非用户只要口头结论——仍应默认落盘报告）
- 漏检正文写死的易变数据（模型窗口/价格/ID——应外置 references/，防过期误导）
- 数据外置检查只查「有没有 references/」，不核对 lastUpdated/refreshInterval/置信度机制
- **不检查 frontmatter 闭合 / description 吞正文**（结构破坏——曾批量中招，属 [高] 级缺陷）
- **放过 WHEN 过宽导致的误触发**（应给反触发建议——deep-codebase-analysis 教训）
- **只查 WHAT+WHEN 齐全、不查触发强度**（标志性能力无触发词 / WHEN 泛泛——合规但永远不被触发；§6.5 pushy 质量）
- **审计改名技能时不查旧名残留**（description **和正文**引用已更名技能名——正文层盲区，product-doc-audit 的 launch 残留教训）
- **旧名检查子串误报 / 把审计反例当残留**（须边界匹配 + 元提及过滤——`*-research/SKILL`、本表 `animation`/`research`/`launch` 反例行）
- **把 fenced code 行首 `#` 当 H1**（代码注释 ≠ 标志性标题）
- **放过 description 中英混杂/中文残留**（判 [低]「可接受」）——库规范**纯英文**，CJK 残留（含格式示例/头部标签）即 **[中]**，须报修（2026-08-05 教训：project-handoff 中文示例「一句话标题」/ project-intake 头部「项目对接」曾被误判 [低] 未触发修正，用户指出后提高标准）

## 完成标准

- [ ] 未修改被审 `SKILL.md`
- [ ] 同目录存在更新后的 `DESCRIPTION-AUDIT.md`（或用户指定名）
- [ ] 合规表 + 数据外置检查 + 交叉验证矩阵齐全
- [ ] 报告含 **问题**、**建议**、**验收标准** 三节（内容允许为「无」/「无需改动」；有改写时建议回指问题、验收可复测）
- [ ] 假称与标志性缺失已显式判定
- [ ] 数据外置判定已给出（外置完整 / 需外置 / 无该类数据）
- [ ] 结构检查已执行（frontmatter 闭合 / description 不吞正文）
- [ ] 正文非空已判定（或确认在 thin-allowlist.txt）
- [ ] 语言一致性判定已给出（✅ 纯英文 / 中文原生技能纯中文 / ❌ 含中文 [中]——CJK 扫描实证）
- [ ] 误触发防护已评估（WHEN 过宽 → 反触发建议；名称语义/旧名残留已查）
- [ ] pushy 质量已评估（§6.5：标志性能力触发词覆盖 / 场景密度 ≥2 / 高频关键词 / 反触发）
- [ ] 正文层旧名残留已查（改名技能审计时：正文反引号/链接/对齐表引用）
- [ ] 用户收到总评与报告路径