utility-pm-skill-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PM Skill Validate

PM Skill 验证工具

This skill audits an existing pm-skills skill against the repo's structural conventions and quality criteria. It produces a validation report that a human can scan and that

/pm-skill-iterate

can consume as input.

The validator checks two tiers:

Tier 1 (Structural) . deterministic checks that mirror CI: frontmatter, naming, file presence, description word count.
Tier 2 (Quality) . LLM-assessed coherence checks: does the output contract reference the template? Is the example complete? Are checklist items testable?

本技能针对代码仓库中现有的pm-skills技能，依据结构规范和质量标准进行审核。它会生成一份验证报告，既可供人工快速查看，也可作为输入供

/pm-skill-iterate

技能使用。

验证器包含两个层级的检查：

层级1（结构检查）：与CI流程一致的确定性检查，包括前置元数据（frontmatter）、命名规范、文件存在性、描述字数统计。
层级2（质量检查）：由LLM评估的一致性检查，例如输出契约是否引用模板？示例是否完整？检查清单项是否可测试？

When to Use

使用场景

After creating a skill with
```
/pm-skill-builder
```
, before shipping
After manually editing a skill, to confirm it still passes conventions
Before running
```
/pm-skill-iterate
```
, to identify what needs improvement
When a convention changes, to audit which skills need updating (batch mode)
When reviewing a contributed skill for quality and completeness

使用
```
/pm-skill-builder
```
创建技能后，发布之前
手动编辑技能后，确认其仍符合规范
运行
```
/pm-skill-iterate
```
之前，识别需要改进的内容
当规范变更时，批量审核哪些技能需要更新（批量模式）
审核贡献的技能，检查其质量与完整性

When NOT to Use

不适用场景

To create a new skill from scratch -> use
```
/pm-skill-builder
```
To fix or improve a skill -> use
```
/pm-skill-iterate
```
(feed it this report)
To run CI checks in a pipeline -> use
```
scripts/lint-skills-frontmatter.sh
```
(this skill is for interactive, deeper-than-CI validation)

从零创建新技能 → 使用
```
/pm-skill-builder
```
修复或改进技能 → 使用
```
/pm-skill-iterate
```
（将本报告作为输入）
在流水线中运行CI检查 → 使用
```
scripts/lint-skills-frontmatter.sh
```
（本技能用于交互式、比CI更深入的验证）

Instructions

操作步骤

When asked to validate a skill, follow these steps:

当被要求验证技能时，请遵循以下步骤：

Step 1: Identify the Target

步骤1：确定目标技能

Accept the skill name in any form:

Directory name:
```
deliver-prd
```
Full path:
```
skills/deliver-prd/SKILL.md
```
Slash command:
```
/prd
```

Resolve to the canonical directory path:

skills/{name}/

If the skill directory does not exist, report immediately:

undefined

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

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

将其解析为标准目录路径：

skills/{name}/

。

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

undefined

Validation Report: {input}

Result: FAIL Skill directory

skills/{input}/

does not exist.


**Batch mode:** If the input is `--all`, run Tier 1 structural checks
across all skills and produce a summary table (see Step 5). Do not run
Tier 2 in batch mode.

Result: FAIL Skill directory

skills/{input}/

does not exist.


**批量模式**：若输入为`--all`，则对所有技能运行层级1的结构检查，并生成汇总表格（见步骤5）。批量模式下不运行层级2检查。

Step 2: Read Skill Files

步骤2：读取技能文件

Read all files in the skill directory:

File	Required	Purpose
`SKILL.md`	yes	Frontmatter + instructions
`references/TEMPLATE.md`	yes	Output template
`references/EXAMPLE.md`	yes	Worked example
`HISTORY.md`	no	Version history (if present)

文件	是否必填	用途
`SKILL.md`	是	前置元数据 + 操作说明
`references/TEMPLATE.md`	是	输出模板
`references/EXAMPLE.md`	是	示例案例
`HISTORY.md`	否	版本历史（若存在）

Step 3: Run Tier 1 . Structural Checks

步骤3：运行层级1（结构检查）

Run these deterministic checks. Each produces a

PASS

FAIL

line.

Check ID	What to check	Pass condition
`name-match`	Frontmatter `name` matches directory name	Exact string match
`description-present`	Frontmatter `description` exists	Non-empty value
`description-length`	Description word count	20-100 words
`version-present`	Frontmatter `version` exists	Non-empty, valid SemVer
`updated-present`	Frontmatter `updated` exists	Non-empty, ISO date
`license-present`	Frontmatter `license` exists	Non-empty value
`phase-classification`	Phase/classification consistency	Domain has `phase:` , foundation/utility has `classification:` , not both
`template-exists`	`references/TEMPLATE.md` exists	File present
`template-sections`	TEMPLATE.md has sufficient structure	≥3 `##` level-2 headers
`example-exists`	`references/EXAMPLE.md` exists	File present
`command-exists`	Command file exists in `commands/`	File present and references correct skill path
`agents-entry`	AGENTS.md has an entry for this skill	Entry exists with matching `Path:`

执行以下确定性检查，每项检查生成一条

PASS

或

FAIL

记录。

检查ID	检查内容	通过条件
`name-match`	前置元数据 `name` 与目录名一致	完全字符串匹配
`description-present`	前置元数据 `description` 存在	值非空
`description-length`	描述字数	20-100词
`version-present`	前置元数据 `version` 存在	值非空且符合SemVer规范
`updated-present`	前置元数据 `updated` 存在	值非空且为ISO格式日期
`license-present`	前置元数据 `license` 存在	值非空
`phase-classification`	阶段/分类一致性	领域类技能包含 `phase:` ，基础/工具类技能包含 `classification:` ，不可同时存在两者
`template-exists`	`references/TEMPLATE.md` 存在	文件已存在
`template-sections`	TEMPLATE.md具有足够结构	包含≥3个 `##` 二级标题
`example-exists`	`references/EXAMPLE.md` 存在	文件已存在
`command-exists`	命令文件存在于 `commands/` 目录	文件存在且引用正确的技能路径
`agents-entry`	AGENTS.md中存在该技能的条目	条目存在且 `Path:` 匹配

Step 4: Run Tier 2 . Quality Checks

步骤4：运行层级2（质量检查）

Run these LLM-assessed checks. Each produces a

PASS

WARN

, or

INFO

line. Tier 2 findings are capped at

WARN

unless objectively grounded (placeholder leakage is the exception . it can

FAIL

Check ID	What to assess	How to assess	Max severity
`output-contract-coverage`	SKILL.md references the template	Check for explicit reference to `references/TEMPLATE.md` or "use the template" in an Output section. Accept either pattern as valid. WARN only if template is not referenced at all.	WARN
`checklist-verifiability`	Quality checklist items are testable	Read each checklist item. Flag items that are vague ("is good quality") vs. specific ("metrics are measurable"). WARN if ≥2 items are vague.	WARN
`example-completeness`	EXAMPLE.md fills all template sections	Compare `##` headers in TEMPLATE.md against `##` headers in EXAMPLE.md. WARN if EXAMPLE.md is missing sections that appear in the template. Also check for unresolved placeholders. Line count is informational only . report it but do not gate on it.	WARN
`template-example-alignment`	EXAMPLE.md follows TEMPLATE.md structure	Compare section header ordering. WARN if EXAMPLE.md has sections in a different order or uses different header names than TEMPLATE.md.	WARN
`description-actionability`	Description tells when to use the skill	Check for a trigger phrase like "Use when..." or "Use for..." in the frontmatter description. WARN if the description only says what the skill does without indicating when to use it.	WARN
`instruction-clarity`	Instructions are numbered and imperative	Check for `### Step` headings or a numbered list pattern in the Instructions section. WARN if instructions are prose paragraphs without clear step structure.	WARN
`placeholder-leakage`	No leftover scaffolding in any shipped file	Scan SKILL.md, TEMPLATE.md, and EXAMPLE.md for: `[Placeholder]` or `[Feature Name]` patterns, `<!-- ... -->` HTML comments (except the license header), template guidance blockquotes that should have been removed, and authoring notes like "TODO" or "FIXME". FAIL if any are found . this is objectively grounded.	FAIL
`when-not-to-use`	"When NOT to Use" section present in SKILL.md	Check for a section with "When NOT to Use" or similar heading. INFO only . this is present in 1/27 shipped skills and is not yet a convention.	INFO

Quality standard framing: These checks validate against current library conventions . what the shipped library actually does today. Findings graded WARN or INFO represent the v2.8 quality standard that newer skills (built with

/pm-skill-builder

) meet. Older skills may legitimately receive these findings until iterated through the lifecycle.

执行以下由LLM评估的检查，每项检查生成一条

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章节顺序或标题名称与TEMPLATE.md不一致则标记为WARN。	WARN
`description-actionability`	描述是否说明技能的使用时机	检查前置元数据描述中是否包含"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`	SKILL.md中是否包含"When NOT to Use"章节	检查是否存在标题为"When NOT to Use"或类似的章节。仅作INFO标记——目前已发布的27个技能中仅有1个包含此章节，尚未成为规范。	INFO

质量标准说明：这些检查基于当前技能库的规范——即已发布技能库实际遵循的标准。WARN或INFO级别的结果代表v2.8质量标准，是使用

/pm-skill-builder

创建的新技能需满足的要求。旧技能在迭代更新前可能会收到此类结果，属于正常情况。

Step 5: Produce the Validation Report

步骤5：生成验证报告

Assemble the report using this exact structure. F-11 (

/pm-skill-iterate

) parses this report by section headings and pipe-delimited fields.

undefined

按照以下精确结构组装报告。F-11（

/pm-skill-iterate

）会通过章节标题和竖线分隔字段解析本报告。

undefined

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.

{1-2句话的整体评估。} 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} ...

{STATUS} | structural | {check-id} | {message}
{STATUS} | structural | {check-id} | {message} ...

Quality Checks

{STATUS} | quality | {check-id} | {message}
{STATUS} | quality | {check-id} | {message} ...

{STATUS} | quality | {check-id} | {message}
{STATUS} | quality | {check-id} | {message} ...

Recommendations

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


**Report rules:**

- **Result** = worst severity found: any FAIL → `FAIL`, else any WARN → `WARN`, else `PASS`.
- **Structural Checks**: one line per Tier 1 check. STATUS is `PASS` or `FAIL`.
- **Quality Checks**: one line per Tier 2 check. STATUS is `PASS`, `WARN`, or `INFO`.
- **Recommendations**: only include checks that did NOT pass. Each recommendation
  includes the check ID, the target file path, and a specific action.
- If all checks pass, the Recommendations section should say: "No issues found."
- Omit passing checks from Recommendations . only list findings that need action.

**Batch mode output** (when input is `--all`):

Run Tier 1 structural checks only across all skills. Produce a summary table:

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


**报告规则**：

- **Result** = 检查到的最高严重度：存在任意FAIL → `FAIL`，否则存在任意WARN → `WARN`，否则`PASS`。
- **Structural Checks**：每个层级1检查对应一行。STATUS为`PASS`或`FAIL`。
- **Quality Checks**：每个层级2检查对应一行。STATUS为`PASS`、`WARN`或`INFO`。
- **Recommendations**：仅包含未通过的检查。每条建议需包含检查ID、目标文件路径和具体操作。
- 若所有检查通过，Recommendations章节应显示："No issues found."
- 已通过的检查不列入Recommendations——仅列出需要处理的问题。

**批量模式输出**（输入为`--all`时）：

仅对所有技能运行层级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

/pm-skill-validate {skill}

for a detailed report.

undefined

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

/pm-skill-validate {skill}

for a detailed report.

undefined

Degraded Mode

降级模式

If you cannot read skill files directly (e.g., running via MCP or in an embedded environment without file system access):

Ask the user to provide the content of each required file:

```
skills/{name}/SKILL.md
```
```
skills/{name}/references/TEMPLATE.md
```
```
skills/{name}/references/EXAMPLE.md
```

Run all checks against the provided content.
Note in the report: "Validated from user-provided content (file system not available)."
Batch mode is not available in degraded mode . single skill only.

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

请求用户提供每个必填文件的内容：

```
skills/{name}/SKILL.md
```
```
skills/{name}/references/TEMPLATE.md
```
```
skills/{name}/references/EXAMPLE.md
```

基于提供的内容执行所有检查。
在报告中注明："Validated from user-provided content (file system not available)."
降级模式下不支持批量模式——仅可验证单个技能。

Output Contract

输出契约

The validator MUST produce a validation report following the format in Step 5.

The report:

Uses the exact section headings:

## Summary

## Structural Checks

## Quality Checks

## Recommendations

Uses pipe-delimited check lines:
```
STATUS | TIER | CHECK-ID | message
```
Uses pipe-delimited recommendations:
```
STATUS | CHECK-ID | Target: path
```
followed by
```
Action: description
```
on the next line
Includes
```
Report schema: v1
```
in the header for F-11 compatibility
Includes the Tier 2 caveat line in the Summary section

验证器必须按照步骤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章节包含层级2检查的提示行

Quality Checklist

质量检查清单

Examples

示例

See

references/EXAMPLE.md

for a completed validation report demonstrating both Tier 1 and Tier 2 checks against a real shipped skill.

请查看

references/EXAMPLE.md

获取完整的验证报告示例，展示针对已发布技能的层级1和层级2检查结果。