---
title: "PM Skill Validate"
description: "Audits an existing pm-skills skill against structural conventions and quality criteria. Produces a structured validation report with pass/fail checks, severity-graded findings, and actionable recommendations. Use when checking whether a skill meets repo standards before shipping or after making changes."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Utility
  - coordination
---

:::note[Quick facts]
**Classification:** Utility | **Version:** 1.0.0 | **Category:** coordination | **License:** Apache-2.0
:::

**Try it:** `/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 `/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 `/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

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

## How to Use

Use the `/pm-skill-validate` slash command:

```
/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: `/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) |

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

### 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:**` |

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

### Step 5: Produce the Validation Report

Assemble the report using this exact structure. F-11 (`/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}

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

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

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

## Example Output

<details>
<summary>Validation Report: deliver-prd</summary>

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

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . validating the campaign-analytics skill from skill builder output</summary>

**Prompt:**

```
/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

</details>

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

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