Audits pm-skills skills against structural conventions and quality criteria. Produces validation reports with pass/fail checks, severity-graded findings, and recommendations. Use before shipping or after changes.
From pm-skillsnpx claudepluginhub product-on-purpose/pm-skillsThis skill uses the workspace's default tool permissions.
references/EXAMPLE.mdreferences/TEMPLATE.mdEnables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Guides agentic engineering workflows: eval-first loops, 15-min task decomposition, model routing (Haiku/Sonnet/Opus), AI code reviews, and cost tracking.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
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:
/pm-skill-builder, before shipping/pm-skill-iterate, to identify what needs improvement/pm-skill-builder/pm-skill-iterate (feed it this report)scripts/lint-skills-frontmatter.sh
(this skill is for interactive, deeper-than-CI validation)When asked to validate a skill, follow these steps:
Accept the skill name in any form:
deliver-prdskills/deliver-prd/SKILL.md/prdResolve 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.
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:
commands/{command-name}.mdIf reading files is not possible (MCP/embedded environment), ask the user to paste the content of each file before proceeding (see Degraded Mode).
Run these deterministic checks. Each produces a PASS or 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:** |
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.
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}
## 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:
FAIL, else any WARN → WARN, else PASS.PASS or FAIL.PASS, WARN, or INFO.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 `/pm-skill-validate {skill}` for a detailed report.
If you cannot read skill files directly (e.g., running via MCP or in an embedded environment without file system access):
skills/{name}/SKILL.mdskills/{name}/references/TEMPLATE.mdskills/{name}/references/EXAMPLE.mdThe validator MUST produce a validation report following the format in Step 5.
The report:
## Summary, ## Structural Checks,
## Quality Checks, ## RecommendationsSTATUS | TIER | CHECK-ID | messageSTATUS | CHECK-ID | Target: path
followed by Action: description on the next lineReport schema: v1 in the header for F-11 compatibilityBefore delivering the report, verify:
See references/EXAMPLE.md for a completed validation report demonstrating
both Tier 1 and Tier 2 checks against a real shipped skill.