Back to Details

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}

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:
FileRequiredPurpose
SKILL.md
yesFrontmatter + instructions
references/TEMPLATE.md
yesOutput template
references/EXAMPLE.md
yesWorked example
HISTORY.md
noVersion history (if present)
Also read:
  • The corresponding command file: 
    commands/{command-name}.md
  • The AGENTS.md entry for this skill
If reading files is not possible (MCP/embedded environment), ask the user to paste the content of each file before proceeding (see Degraded Mode).
读取技能目录下的所有文件：
文件是否必填用途
SKILL.md
是前置元数据 + 操作说明
references/TEMPLATE.md
是输出模板
references/EXAMPLE.md
是示例案例
HISTORY.md
否版本历史（若存在）
同时读取：
  • 对应的命令文件：
    commands/{command-name}.md
  • AGENTS.md中该技能的条目
若无法读取文件（如MCP/嵌入式环境），请用户粘贴每个文件的内容后再继续（见降级模式）。

Step 3: Run Tier 1 . Structural Checks

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

Run these deterministic checks. Each produces a 
PASS
or 
FAIL
line.
Check IDWhat to checkPass condition
name-match
Frontmatter 
name
matches directory name		Exact string match
description-present
Frontmatter 
description
exists		Non-empty value
description-length
Description word count20-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 consistencyDomain 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 skillEntry 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 IDWhat to assessHow to assessMax severity
output-contract-coverage
SKILL.md references the templateCheck 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 testableRead 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 sectionsCompare 
##
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 structureCompare 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 skillCheck 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 imperativeCheck 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 fileScan 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.mdCheck 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}

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}
Date: {YYYY-MM-DD} Skill version: {version from frontmatter} Validator version: 1.0.0 Report schema: v1 Result: {PASS | WARN | FAIL}

Summary

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

Structural Checks

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

Quality Checks

Quality Checks

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

Recommendations

Recommendations

  1. {STATUS} | {check-id} | Target: {file-path} Action: {what to do}
  2. {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:
  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**：每个层级1检查对应一行。STATUS为`PASS`或`FAIL`。
- **Quality Checks**：每个层级2检查对应一行。STATUS为`PASS`、`WARN`或`INFO`。
- **Recommendations**：仅包含未通过的检查。每条建议需包含检查ID、目标文件路径和具体操作。
- 若所有检查通过，Recommendations章节应显示："No issues found."
- 已通过的检查不列入Recommendations——仅列出需要处理的问题。

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

仅对所有技能运行层级1结构检查，生成汇总表格：

Batch Validation Summary

Batch Validation Summary

Date: {YYYY-MM-DD} Validator version: 1.0.0 Report schema: v1 Skills checked: {n}
SkillResultErrorsWarnings
deliver-prdPASS00
define-hypothesisWARN01
foundation-personaFAIL10
...
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}
SkillResultErrorsWarnings
deliver-prdPASS00
define-hypothesisWARN01
foundation-personaFAIL10
...
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):
  1. 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
  2. Run all checks against the provided content.
  3. Note in the report: "Validated from user-provided content (file system not available)."
  4. Batch mode is not available in degraded mode . single skill only.
若无法直接读取技能文件（如通过MCP运行或在无文件系统访问权限的嵌入式环境中）：
  1. 请求用户提供每个必填文件的内容： 
    • skills/{name}/SKILL.md
    • skills/{name}/references/TEMPLATE.md
    • skills/{name}/references/EXAMPLE.md
  2. 基于提供的内容执行所有检查。
  3. 在报告中注明："Validated from user-provided content (file system not available)."
  4. 降级模式下不支持批量模式——仅可验证单个技能。

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

质量检查清单

Before delivering the report, verify:
  • All Tier 1 structural checks were run (not skipped)
  • All Tier 2 quality checks were run (not skipped) . single skill mode only
  • Report follows the exact section and line format from Step 5
  • Every non-passing check appears in Recommendations with a target file path
  • Result field reflects the worst severity found
  • Tier 2 findings are capped at WARN (except placeholder-leakage which can FAIL)
  • No Tier 2 check was marked FAIL unless objectively grounded
交付报告前，请验证：
  • 所有层级1结构检查已执行（未跳过）
  • 所有层级2质量检查已执行（未跳过）——仅单技能模式
  • 报告严格遵循步骤5中的章节和行格式
  • 每个未通过的检查均在Recommendations中列出，并包含目标文件路径
  • Result字段反映检查到的最高严重度
  • 层级2检查结果最高为WARN（placeholder-leakage除外，可标记为FAIL）
  • 层级2检查仅在有客观依据时才标记为FAIL

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检查结果。