PM Skill Validate

Try it: /pm-skills:utility-pm-skill-validate "Your context here"

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 utility-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?

When to Use

After creating a skill with utility-pm-skill-builder, before shipping
After manually editing a skill, to confirm it still passes conventions
Before running utility-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

When NOT to Use

To create a new skill from scratch -> use utility-pm-skill-builder
To fix or improve a skill -> use utility-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)

How to Use

Invoke the skill by name (/pm-skills:utility-pm-skill-validate on Claude Code, $utility-pm-skill-validate on Codex):

/pm-skills:utility-pm-skill-validate "Your context here"

Or reference the skill file directly: skills/utility-pm-skill-validate/SKILL.md

Instructions

When asked to validate a skill, follow these steps:

Step 1: Identify the Target

Accept the skill name in any form:

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

Resolve to the canonical directory path: skills/{name}/.

If the skill directory does not exist, report immediately:

# 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.

Step 2: Read Skill Files

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)
`evals/trigger-fixtures.json`	no	Routing-eval fixtures (B-4); present for roster skills
`evals/output-scenarios/*.md`	no	Output-quality scenarios (B-7); present for evaled skills

Step 3: Run Tier 1 - Structural Checks

Run these deterministic checks. Each produces a PASS or FAIL line.

Check ID	What to check	Pass condition
`frontmatter-at-byte-zero`	First line of SKILL.md, references/TEMPLATE.md, references/EXAMPLE.md is exactly `---`	Line 1 is the opening `---` fence with no preceding HTML comment, BOM, or whitespace. Severity: FAIL. Reference: `library/skill-output-samples/SAMPLE_CREATION.md` Section 5.
`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:`
`eval-trigger-fixtures`	Routing fixtures present + well-formed (B-4)	If `evals/trigger-fixtures.json` exists: `schema:1`, `skill` matches dir, >=16 queries, >=8 per class (trigger / no-trigger), >=2 near-misses. If absent: INFO (not in the trigger-eval roster, or fixtures not yet authored). Authoritative gate: `scripts/check-trigger-fixtures.mjs`.
`eval-output-scenarios`	Output scenarios present + well-formed (B-7)	If `evals/output-scenarios/*.md` exist: each has `scenario`/`skill`/`family` frontmatter, `skill` matches dir, `family` maps to an existing `docs/internal/eval-rubrics/{family}.md`, body >=100 chars. If absent: INFO (not yet output-evaled). Authoritative gate: `scripts/check-output-eval-assets.mjs`.
`reciprocal-boundary-pointers`	Declared collision pairs cross-point (C-5)	If the skill appears in `COLLISION_PAIRS` (`scripts/check-trigger-fixtures.mjs`): its `When NOT to Use` names each partner AND each partner’s `When NOT to Use` names it back. FAIL if a declared pair is one-directional. If not in any pair: PASS. Authoritative gate: `scripts/check-reciprocal-boundary-pointers.mjs`.

Step 4: Run Tier 2 - Quality Checks

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 and names neighbors	Check for a `When NOT to Use` section that names the skill’s nearest neighbors (when to use them instead). WARN if the section is absent, or present but generic (no neighbor named). This became a convention in the v2.26.0 rewrites and underpins the reciprocity gate; `reciprocal-boundary-pointers` (Tier 1) is the deterministic backstop for declared collision pairs.	WARN

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 utility-pm-skill-builder) meet. Older skills may legitimately receive these findings until iterated through the lifecycle.

Heading and dialect conventions: for the authoritative section skeleton per dialect (classic, contract-shaped, tool-family) and the exact canon heading spellings, see Skeleton Canon: The Three Sanctioned Dialects in the skill-authoring guide. A skill whose headings or section set drift from its dialect’s canon should be flagged in Recommendations even where no Tier 1 check above already covers it; scripts/check-heading-canon.mjs is the eventual deterministic backstop, shipping advisory until the full catalog is normalized.

Step 5: Produce the Validation Report

Assemble the report using this exact structure. F-11 (utility-pm-skill-iterate) parses this report by section headings and pipe-delimited fields.

# 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}
...

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:

# 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.

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.

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

Examples

See references/EXAMPLE.md for a completed validation report demonstrating both Tier 1 and Tier 2 checks against a real shipped skill.

Output Template

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 of the skill’s compliance with structural conventions and quality criteria.}

Errors: {n} | Warnings: {n} | Info: {n}

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

Structural Checks

{One line per Tier 1 check. Use pipe-delimited format:}

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

{Include all checks from the Tier 1 table in SKILL.md Step 3. STATUS is PASS or FAIL.}

Quality Checks

{One line per Tier 2 check. Use pipe-delimited format:}

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

{Include all checks from the Tier 2 table in SKILL.md Step 4. STATUS is PASS, WARN, or INFO. Tier 2 findings capped at WARN unless objectively grounded (placeholder-leakage can FAIL).}

Recommendations

{Only include checks that did NOT pass. Each recommendation includes the check ID, target file path, and a specific action.}

{STATUS} | {check-id} | Target: {file-path} Action: {what to do to resolve this finding}

{If all checks pass, write: “No issues found.”}

Example Output

Validation Report: deliver-prd

Date: 2026-04-03 Skill version: 2.0.0 Validator version: 1.0.0 Report schema: v1 Result: WARN

Summary

deliver-prd passes all structural checks. Two quality findings: the output contract uses a generic template reference (acceptable but below v2.8 standard), and the skill lacks a “When NOT to Use” section (informational).

Errors: 0 | Warnings: 1 | Info: 1

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

Structural Checks

PASS | structural | name-match | frontmatter name matches directory
PASS | structural | description-present | description exists
PASS | structural | description-length | 31 words (20-100 range)
PASS | structural | version-present | version “2.0.0”
PASS | structural | updated-present | updated 2026-01-26
PASS | structural | license-present | Apache-2.0
PASS | structural | phase-classification | phase: deliver (domain skill, no classification field)
PASS | structural | template-exists | references/TEMPLATE.md present
PASS | structural | template-sections | 10 level-2 headers (≥3 required)
PASS | structural | example-exists | references/EXAMPLE.md present
PASS | structural | command-exists | commands/prd.md exists and references correct path
PASS | structural | agents-entry | AGENTS.md entry found with matching path

Quality Checks

WARN | quality | output-contract-coverage | Output Format section says “Use the template in references/TEMPLATE.md to structure the output” but does not enumerate template sections explicitly. Accepted as valid - this is the current library convention.
PASS | quality | checklist-verifiability | all 7 checklist items are specific and testable (e.g., “Success metrics are specific and measurable”, “Document is readable in under 15 minutes”)
PASS | quality | example-completeness | EXAMPLE.md fills all 10 template sections with concrete content. No placeholder scaffolding detected. Line count: 212 (informational).
PASS | quality | template-example-alignment | EXAMPLE.md section headers match TEMPLATE.md in order and naming
PASS | quality | description-actionability | description includes trigger phrase: “Use when specifying features, epics, or product initiatives for engineering handoff”
PASS | quality | instruction-clarity | 8 numbered steps with imperative verbs (Summarize, Define, Outline, Detail, Define, Address, Identify, Propose)
PASS | quality | placeholder-leakage | no unresolved placeholders, HTML comments (except license header), or authoring notes found
INFO | quality | when-not-to-use | no “When NOT to Use” section present (optional - present in 1/27 shipped skills)

Recommendations

WARN | output-contract-coverage | Target: skills/deliver-prd/SKILL.md Action: Consider enumerating the template sections explicitly in the Output Format section (e.g., “The output MUST include: Problem Summary, Goals, Solution Overview…”). Current generic reference is valid but below v2.8 standard.
INFO | when-not-to-use | Target: skills/deliver-prd/SKILL.md Action: Consider adding a “When NOT to Use” section to help users pick the right skill. Example: “Not for lightweight feature briefs -> use solution-brief instead.”

Example Notes

This report demonstrates:

All 12 Tier 1 structural checks passing (common for shipped skills)
Tier 2 quality checks surfacing one WARN and one INFO against a well-established skill
The WARN for output-contract-coverage illustrates the “current conventions vs. v2.8 standard” framing - the skill is valid by current standards, but the validator surfaces the higher standard as a suggestion
The INFO for when-not-to-use illustrates a finding that is purely optional guidance
Recommendations include target file paths and specific actions for each finding
The overall Result is WARN (worst severity found), not FAIL

Real-World Examples

See this skill applied to three different product contexts:

Storevine (B2B): Storevine B2B ecommerce platform . validating the campaign-analytics skill from skill builder output

Prompt:

utility-pm-skill-validate

Skill: campaign-analytics
Path: skills/measure-campaign-analytics/

Output:

Validation Report: campaign-analytics

Date: 2026-04-11 Skill version: 1.0.0 Validator version: 1.0.0 Report schema: v1 Result: WARN

Quality Checklist

Before delivering the report, verify:

All Tier 1 structural checks were run (not skipped), including the eval-asset checks (eval-trigger-fixtures, eval-output-scenarios, reciprocal-boundary-pointers); absent eval assets are INFO, not FAIL, except a one-directional declared collision pair which FAILs
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