/utility-pm-skill-validate

name: utility-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.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.2.0"
  updated: 2026-07-04
  category: coordination
  frameworks: [triple-diamond]
  author: product-on-purpose

PM Skill Validate

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)

• To audit the whole catalog rather than one skill -> use `utility-pm-skill-auditor`. This skill goes deep on a single skill; the auditor goes wide across the repo and aggregates cross-cutting findings.

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 |

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