utility-pm-skill-validate

PM 技能验证

此技能会根据仓库的结构规范和质量标准，审查现有的 pm-skills 技能。它会生成一份验证报告，供人工快速查看，也可由 utility-pm-skill-iterate 作为输入使用。

验证器会检查两个层级：

• Tier 1（结构）——确定性检查，与 CI 检查保持一致：frontmatter、命名、文件是否存在、描述的字数。
• Tier 2（质量）——由 LLM 评估的一致性检查：输出约定是否引用模板？示例是否完整？清单项目是否可测试？

适用场景

• 使用 utility-pm-skill-builder 创建技能后、发布前
• 手动编辑技能后，确认其仍符合规范
• 运行 utility-pm-skill-iterate 前，确定需要改进的地方
• 规范发生变化时，审查哪些技能需要更新（批量模式）
• 审核贡献的技能，检查其质量和完整性

不适用场景

• 从零创建新技能 → 使用 utility-pm-skill-builder
• 修复或改进技能 → 使用 utility-pm-skill-iterate（将此报告提供给它）
• 在流水线中运行 CI 检查 → 使用 scripts/lint-skills-frontmatter.sh （此技能用于交互式验证，检查范围比 CI 更深入）
• 审查整个目录，而非单个技能 → 使用 utility-pm-skill-auditor。此技能深入审查单个技能；审计器则全面扫描整个仓库，并汇总跨领域发现。

说明

收到验证技能的请求时，请按以下步骤操作：

步骤 1：确定目标

接受以下任意形式的技能名称：

• 目录名：deliver-prd
• 完整路径：skills/deliver-prd/SKILL.md
• 斜杠命令：deliver-prd

解析为规范目录路径：skills/{name}/。

如果技能目录不存在，请立即报告：

# Validation Report: {input}
Result: FAIL
Skill directory `skills/{input}/` does not exist.

批量模式： 如果输入为 --all，请对所有技能运行 Tier 1 结构检查，并生成汇总表（见步骤 5）。批量模式下不要运行 Tier 2。

步骤 2：读取技能文件

读取技能目录中的所有文件：

文件	必需	用途
SKILL.md	是	Frontmatter 和说明
references/TEMPLATE.md	是	输出模板
references/EXAMPLE.md	是	完整示例
HISTORY.md	否	版本历史（如果存在）
evals/trigger-fixtures.json	否	路由评估用例（B-4）；名册类技能会包含此文件
evals/output-scenarios/*.md	否	输出质量场景（B-7）；经过评估的技能会包含此文件

另请读取：

• 对应的命令文件：commands/{command-name}.md
• 此技能在 AGENTS.md 中的条目

如果无法读取文件（MCP/嵌入式环境），请先要求用户粘贴每个文件的内容，再继续（参见“降级模式”）。

步骤 3：运行第 1 级——结构检查

运行以下确定性检查。每项检查都会输出一行 PASS 或 FAIL。

检查 ID	检查内容	通过条件
frontmatter-at-byte-zero	SKILL.md、references/TEMPLATE.md、references/EXAMPLE.md 的第一行是否完全为 ---	第 1 行是起始 --- 分隔符，前面没有 HTML 注释、BOM 或空白。严重级别：FAIL。参考：library/skill-output-samples/SAMPLE_CREATION.md 第 5 节。
name-match	Frontmatter 中的 name 是否与目录名匹配	字符串完全匹配
description-present	Frontmatter 中是否存在 description	值非空
description-length	Description 的字数	20-100 个单词
version-present	Frontmatter 中是否存在 version	值非空，且为有效的 SemVer
updated-present	Frontmatter 中是否存在 updated	值非空，且为 ISO 日期
license-present	Frontmatter 中是否存在 license	值非空
phase-classification	阶段/分类是否一致	Domain 有 phase:，foundation/utility 有 classification:，不可同时存在
template-exists	references/TEMPLATE.md 是否存在	文件存在
template-sections	TEMPLATE.md 是否具有足够的结构	至少有 3 个 ## 二级标题
example-exists	references/EXAMPLE.md 是否存在	文件存在
command-exists	commands/ 中是否存在命令文件	文件存在，且引用了正确的技能路径
agents-entry	AGENTS.md 中是否有此技能的条目	条目存在，且 **Path:** 匹配
eval-trigger-fixtures	路由测试样例是否存在且格式正确（B-4）	如果存在 evals/trigger-fixtures.json：需满足 schema:1、skill 与目录匹配、查询数不少于 16 条、每类（trigger / no-trigger）不少于 8 条、near-miss 不少于 2 条。如果不存在：INFO（不在 trigger-eval 名单中，或尚未编写测试样例）。权威检查：scripts/check-trigger-fixtures.mjs。
eval-output-scenarios	输出场景是否存在且格式正确（B-7）	如果存在 evals/output-scenarios/*.md：每个文件都必须有 scenario/skill/family frontmatter，skill 与目录匹配，family 对应现有的 docs/internal/eval-rubrics/{family}.md，正文不少于 100 个字符。如果不存在：INFO（尚未进行输出评估）。权威检查：scripts/check-output-eval-assets.mjs。
reciprocal-boundary-pointers	声明的冲突配对是否互相指向（C-5）	如果此技能出现在 COLLISION_PAIRS（scripts/check-trigger-fixtures.mjs）中：其 When NOT to Use 必须列出每个配对技能，且每个配对技能的 When NOT to Use 也必须反向列出此技能。若声明的配对只有单向指向，则 FAIL。如果不在任何配对中：PASS。权威检查：scripts/check-reciprocal-boundary-pointers.mjs。

步骤 4：运行第 2 层质量检查

运行以下由大模型评估的检查。每项检查都会生成一行 PASS、WARN 或 INFO。 除非有客观依据，否则第 2 层检查结果最高为 WARN（占位符泄漏除外——此项可能判为 FAIL）。

检查 ID	评估内容	评估方法	最高严重级别
output-contract-coverage	SKILL.md 是否引用模板	检查是否在 Output 部分明确引用 references/TEMPLATE.md 或“use the template”。任一模式都视为有效。只有完全未引用模板时才标记为 WARN。	WARN
checklist-verifiability	质量检查清单中的条目是否可测试	阅读每项检查清单。标记含糊的条目（如“质量好”），而非具体条目（如“指标可衡量”）。若 ≥2 项含糊，则标记为 WARN。	WARN
example-completeness	EXAMPLE.md 是否填充了模板的所有部分	比较 TEMPLATE.md 与 EXAMPLE.md 中的 ## 标题。如果 EXAMPLE.md 缺少模板中出现的部分，则标记为 WARN。还要检查是否存在未解决的占位符。行数仅供参考，不作为门槛。	WARN
template-example-alignment	EXAMPLE.md 是否遵循 TEMPLATE.md 的结构	比较各部分标题的顺序。如果 EXAMPLE.md 中的部分顺序不同，或标题名称与模板不同，则标记为 WARN。	WARN
description-actionability	描述是否说明何时使用该技能	检查 frontmatter 描述中是否有“Use when...”或“Use for...”之类的触发短语。如果描述只说明技能的作用，却未指出何时使用，则标记为 WARN。	WARN
instruction-clarity	指令是否编号且采用祈使句	检查 Instructions 部分中是否有 ### Step 标题或编号列表。如果指令只是没有明确步骤结构的散文段落，则标记为 WARN。	WARN
placeholder-leakage	发布文件中是否留有脚手架内容	扫描 SKILL.md、TEMPLATE.md 和 EXAMPLE.md，查找以下内容：[Placeholder] 或 [Feature Name] 模式、`` HTML 注释（许可声明除外）、应已移除的模板指导性引用块，以及“TODO”或“FIXME”等编写备注。如发现任何一项，则判为 FAIL——此项有客观依据。	FAIL
when-not-to-use	是否包含“When NOT to Use”部分并指出相邻技能	检查是否有 When NOT to Use 部分，说明何时应改用最接近的相邻技能。如果该部分缺失，或内容泛泛（未提及相邻技能），则标记为 WARN。这一约定自 v2.26.0 重写起采用，并支撑互惠门槛；reciprocal-boundary-pointers（第 1 层）则是针对已声明冲突对的确定性后备检查。	WARN

质量标准说明： 这些检查依据当前库的规范进行验证，即当前发布的库实际采用的做法。评定为 WARN 或 INFO 的结果体现的是 v2.8 质量标准；使用 utility-pm-skill-builder 构建的新技能符合该标准。旧技能在生命周期迭代之前，可能会合理地出现这些检查结果。

标题与方言规范： 权威的分节骨架（按方言分为 classic、contract-shaped、tool-family）以及规范标题的准确拼写，请参阅技能编写指南中的 Skeleton Canon: The Three Sanctioned Dialects。如果技能的标题或分节集合偏离其方言的规范，即使上方的第 1 层检查未涵盖，也应在 Recommendations 中标记；scripts/check-heading-canon.mjs 最终将作为确定性后备检查，在整个目录完成规范化之前以建议模式发布。

第 5 步：生成验证报告

请严格按以下结构整理报告。F-11（utility-pm-skill-iterate） 会按章节标题和竖线分隔的字段解析此报告。

# Validation Report: {skill-name}
Date: {YYYY-MM-DD}
Skill version: {version from frontmatter}
Validator version: 1.0.0
Report schema: v1
Result: {PASS | WARN | FAIL}

## Summary
{1-2 sentence overall assessment.}
Errors: {n} | Warnings: {n} | Info: {n}

> Tier 2 findings are heuristic quality assessments and may require human review.

## Structural Checks
- {STATUS} | structural | {check-id} | {message}
- {STATUS} | structural | {check-id} | {message}
...

## Quality Checks
- {STATUS} | quality | {check-id} | {message}
- {STATUS} | quality | {check-id} | {message}
...

## Recommendations
1. {STATUS} | {check-id} | Target: {file-path}
   Action: {what to do}
2. {STATUS} | {check-id} | Target: {file-path}
   Action: {what to do}
...

报告规则：

• Result = 发现的最高严重级别：有任何 FAIL → FAIL；否则，有任何 WARN → WARN；否则 → PASS。
• Structural Checks：每项 Tier 1 检查占一行。STATUS 为 PASS 或 FAIL。
• Quality Checks：每项 Tier 2 检查占一行。STATUS 为 PASS、WARN 或 INFO。
• Recommendations：仅包含未通过的检查。每条建议都要包含检查 ID、目标文件路径和具体操作。
• 如果所有检查均通过，Recommendations 部分应写明：“未发现问题。”
• 从 Recommendations 中省略通过的检查，只列出需要采取措施的发现。

批处理模式输出（输入为 --all 时）：

仅对所有技能运行 Tier 1 结构检查。生成汇总表：

# Batch Validation Summary
Date: {YYYY-MM-DD}
Validator version: 1.0.0
Report schema: v1
Skills checked: {n}

| Skill | Result | Errors | Warnings |
|-------|--------|--------|----------|
| deliver-prd | PASS | 0 | 0 |
| define-hypothesis | WARN | 0 | 1 |
| foundation-persona | FAIL | 1 | 0 |
...

Skills passing: {n}/{total}
Run `utility-pm-skill-validate {skill}` for a detailed report.

降级模式

如果无法直接读取技能文件（例如通过 MCP 运行，或在无法访问文件系统的嵌入式环境中运行）：

1. 请用户提供以下必需文件的内容：
   • skills/{name}/SKILL.md
   • skills/{name}/references/TEMPLATE.md
   • skills/{name}/references/EXAMPLE.md
2. 根据用户提供的内容运行所有检查。
3. 在报告中注明：“根据用户提供的内容完成验证（无法访问文件系统）。”
4. 降级模式下不可使用批处理模式，只能验证单个技能。

输出规范

验证器必须按照第 5 步的格式生成验证报告。

报告必须：

• 使用以下准确的章节标题：## Summary、## Structural Checks、 ## Quality Checks、## Recommendations
• 使用竖线分隔的检查行：STATUS | TIER | CHECK-ID | message
• 使用竖线分隔的建议行：STATUS | CHECK-ID | Target: path 下一行写 Action: description
• 在标题中包含 Report schema: v1，以兼容 F-11
• 在 Summary 部分包含 Tier 2 注意事项行

质量检查清单

提交报告前，请确认：

• 已运行所有 Tier 1 结构检查（未跳过），包括 eval 资源检查（eval-trigger-fixtures、eval-output-scenarios、reciprocal-boundary-pointers）；缺少 eval 资源时标记为 INFO，而非 FAIL，但单向声明的冲突配对除外，此情况应标记为 FAIL
• 已运行所有 Tier 2 质量检查（未跳过）——仅限单技能模式
• 报告遵循第 5 步规定的准确章节和行格式
• 每项未通过的检查都已在 Recommendations 中列出，并包含目标文件路径
• Result 字段反映发现的最高严重级别
• Tier 2 发现的严重级别最高为 WARN（placeholder-leakage 除外，它可以是 FAIL）
• 只有在有客观依据时，才将 Tier 2 检查标记为 FAIL

示例

请参阅 references/EXAMPLE.md，其中包含一份已完成的验证报告，展示了如何对实际发布的技能运行 Tier 1 和 Tier 2 检查。