Skip to content
pm-skills

PM Skill Auditor (Dispatch Skill)

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

Cross-client dispatch wrapper for the pm-skill-auditor sub-agent. Detects runtime; dispatches to the native sub-agent on Claude Code; reads agents/pm-skill-auditor.md and executes inline on non-Claude clients.

When to Use

Section titled “When to Use”
  • You need a repo-wide audit pass: all enforcing validators, cross-cutting checks (skill-without-command, sample gaps, family contract orphans, etc.), and aggregate counter re-derivation against declared values in CONTEXT.md + AGENTS.md + README.md
  • You are running on a non-Claude AI client without native pm-skill-auditor sub-agent support
  • You are running on Claude Code and prefer skill-invocation semantics (e.g., for chaining inside a workflow that also uses other dispatch skills)

When NOT to Use

Section titled “When NOT to Use”
  • You want to review a specific PM artifact (PRD, OKR, persona) -> use utility-pm-critic instead
  • You want to draft a CHANGELOG entry -> use utility-pm-changelog-curator (ships in Phase 4)
  • You want to ship a release -> use utility-pm-release-conductor (ships in Phase 5)
  • You want to FIX issues found in an audit -> the auditor is detection-only; remediation is maintainer judgment or future pm-frontmatter-doctor (v2.17+)

How to Use

Section titled “How to Use”

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

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

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

Instructions

Section titled “Instructions”

Runtime detection step. Determine which AI client is invoking this skill.

If you are running in Claude Code with the pm-skills plugin installed

Section titled “If you are running in Claude Code with the pm-skills plugin installed”

Invoke @agent-pm-skills:pm-skill-auditor on the repo. Pass any scope arguments from $ARGUMENTS (e.g., --scope changed, --since-tag v2.15.0, --severity-floor P1). Return the sub-agent’s audit report to the user.

If you are running in any other AI client

Section titled “If you are running in any other AI client”

Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI, or any other client without native pm-skills plugin sub-agent support:

  1. Read the canonical sub-agent definition at agents/pm-skill-auditor.md
  2. Execute the system prompt body in that file as your operating instructions for this turn
  3. Run the four-step audit flow:
    • Step 1: Invoke validators via Bash (prefer bash scripts/pre-tag-validate.sh as canonical entry point)
    • Step 2: Run cross-cutting checks from the catalog at docs/internal/release-plans/v2.16.0/spec_pm-skill-auditor.md#cross-cutting-check-catalog
    • Step 3: Re-derive aggregate counters from filesystem and compare to declared values
    • Step 4: Compose layered output report
  4. Apply scope and severity-floor arguments from $ARGUMENTS
  5. Return the layered output per master plan D26 (full report + Status Summary + Status YAML)

Cross-Client Notes

Section titled “Cross-Client Notes”

See Sub-Agent Compatibility Matrix for the canonical cross-client status. Summary for this skill as of v2.16.0: PRODUCTION on Claude Code + Codex CLI (Codex CLI successfully invoked the validator suite via Bash + produced a layered audit report with re-derived aggregate counters); EXPERIMENTAL on Cursor / Windsurf / Copilot CLI / Gemini CLI.

The “read canonical agent definition and execute inline” pattern depends on the AI client being able to:

  1. Read a referenced file path
  2. Execute Bash to invoke validator scripts
  3. Treat the agent definition body as operating instructions for the current turn

Most AI clients support all three. If any are unreliable on a specific client, that client falls back to manual validator invocation + manual cross-cutting checks.

Reference Files

Section titled “Reference Files”

Output Template

Section titled “Output Template”

Output Template

Section titled “Output Template”

utility-pm-skill-auditor produces a three-section layered output per master plan D26.

Section 1: Full Audit Report

Section titled “Section 1: Full Audit Report”
# pm-skill-auditor report


**Scope:** {full repo at HEAD `{sha}` | changed since HEAD | since-tag {tag}}
**Validators invoked:** {N}
**Cross-cutting checks run:** {N}
**Findings:** N (P0: X, P1: Y, P2: Z, P3: W)


## Validator results


| Validator | Status | Issues |
|---|---|---|
| lint-skills-frontmatter | PASS / FAIL | {count} |
| validate-commands | PASS / FAIL | {count} |
| validate-agents-md | PASS / FAIL | {count} |
| validate-meeting-skills-family | PASS / FAIL | {count} |
| validate-foundation-sprint-skills-family | PASS / FAIL | {count} |
| validate-design-sprint-skills-family | PASS / FAIL | {count} |
| check-internal-link-validity --strict | PASS / FAIL | {count} |
| validate-docs-frontmatter --strict | PASS / FAIL | {count} |
| check-no-body-h1 --strict | PASS / FAIL | {count} |
| check-count-consistency --strict | PASS / FAIL | {count} |
| check-landing-page-counts --strict | PASS / FAIL | {count} |
| check-workflow-generator-coverage | PASS / FAIL | {count} |
| check-agents-md-command-sync | PASS / FAIL | {count} |
| check-generated-content-untouched | PASS / FAIL | {count} |
| check-mcp-impact | PASS / FAIL | {count} |
| (additional validators in pre-tag-validate.sh) | | |


## Cross-cutting findings


### P0 findings


(Per-finding detail using the standard severity grammar from spec_pm-skill-auditor.md. Each finding includes Location / Issue / Why it matters / Fix.)


### P1 findings
### P2 findings
### P3 findings


## Aggregate counter audit


| Surface | Declared | Re-derived | Match |
|---|---|---|---|
| Total skills | {X} | {Y} | YES / NO |
| Phase skills | {X} | {Y} | YES / NO |
| Foundation skills | {X} | {Y} | YES / NO |
| Utility skills | {X} | {Y} | YES / NO |
| Tool skills | {X} | {Y} | YES / NO |
| Sub-agents | {X} | {Y} | YES / NO |
| Commands | {X} | {Y} | YES / NO |
| Workflows | {X} | {Y} | YES / NO |
| Enforcing validators | {X} | {Y} | YES / NO |
| Family contracts | {X} | {Y} | YES / NO |


## Disposition recommendations


- {N} P0 findings: must close before release tag
- {N} P1 findings: close before next major release
- {N} P2 findings: consider in scoping
- {N} P3 findings: skip if time-constrained

Section 2: Status Summary (Prose, for Human Readers)

Section titled “Section 2: Status Summary (Prose, for Human Readers)”
## Status Summary


The audit at {scope} returned {N} findings: {P0: X, P1: Y, P2: Z, P3: W}.


{One paragraph capturing top findings by severity. Counters match? Validators all pass? Cross-cutting issues clustered in a particular area? Explicit recommendation for next action.}


**Refusal triggered:** {yes / no. If yes, explain why per refusal protocols 1-3 in spec_pm-skill-auditor.md.}

Section 3: Status YAML (Machine-Parseable, for Parent Sub-Agent or Tooling)

Section titled “Section 3: Status YAML (Machine-Parseable, for Parent Sub-Agent or Tooling)”
## Status


```yaml
status: pass | fail | refused
p0_count: {integer}
p1_count: {integer}
p2_count: {integer}
p3_count: {integer}
counters_match: true | false
validators_pass: true | false
scope: full | changed | since-tag {tag}
refusal_reason: null | "validators not invocable" | "repo state ambiguous" | "scope unclear"


# Detailed counter breakdown for downstream consumption:
counters:
  declared:
    total_skills: {integer}
    sub_agents: {integer}
    commands: {integer}
    workflows: {integer}
    enforcing_validators: {integer}
  derived:
    total_skills: {integer}
    sub_agents: {integer}
    commands: {integer}
    workflows: {integer}
    enforcing_validators: {integer}


dispatch:
  mode: native-subagent | inline-execution
  client: claude-code | codex-cli | cursor | windsurf | copilot | gemini-cli | other
```

Chained Handoff Notes

Section titled “Chained Handoff Notes”

When invoked from pm-release-conductor at gate G0:

  • All three sections MUST be present
  • The conductor parses Section 3 YAML for advancement decisions
  • The maintainer reads Sections 1 + 2 for human context
  • If status: refused in Section 3, conductor surfaces Section 2 refusal narrative to maintainer
  • If p0_count > 0, conductor blocks advancement past G0 per master plan D23
Section titled “Related Files”

Example Output

Section titled “Example Output”
Example: pm-skill-auditor Dispatch on Cursor

Example: pm-skill-auditor Dispatch on Cursor

Section titled “Example: pm-skill-auditor Dispatch on Cursor”

This example shows what utility-pm-skill-auditor produces when invoked on a non-Claude client (here, Cursor). The dispatch skill reads agents/pm-skill-auditor.md as its operating instructions and executes the four-step audit inline.

Invocation

Section titled “Invocation”
cursor> /utility-pm-skill-auditor --scope full --severity-floor P1

Skill behavior

Section titled “Skill behavior”
  1. Runtime detection. The skill detects it is running in Cursor (not Claude Code with pm-skills plugin), so it takes the non-Claude branch.
  2. Reads canonical sub-agent definition. Loads agents/pm-skill-auditor.md as the operating system prompt.
  3. Step 1 of agent flow: invoke validators. Runs bash scripts/pre-tag-validate.sh (canonical orchestration entry point). Captures output.
  4. Step 2: run cross-cutting checks. Reads catalog from docs/internal/release-plans/v2.16.0/spec_pm-skill-auditor.md#cross-cutting-check-catalog. Runs each check against current repo state.
  5. Step 3: re-derive aggregate counters. Counts skill directories by classification prefix; counts commands; counts sub-agents; compares to declared values.
  6. Step 4: compose layered output. Returns the three-section report below.

Output (verbatim from dispatch skill execution)

Section titled “Output (verbatim from dispatch skill execution)”

pm-skill-auditor report

Section titled “pm-skill-auditor report”

Scope: full repo at HEAD 00b3978 Validators invoked: 16 Cross-cutting checks run: 14 Findings: 4 (P0: 0, P1: 2, P2: 2, P3: 0 [hidden by —severity-floor P1])

Validator results

Section titled “Validator results”
ValidatorStatusIssues
lint-skills-frontmatterPASS0
validate-commandsPASS0
validate-agents-mdPASS0
validate-meeting-skills-familyPASS0
validate-foundation-sprint-skills-familyPASS0
validate-design-sprint-skills-familyPASS0
check-internal-link-validity —strictPASS0
validate-docs-frontmatter —strictPASS0
check-no-body-h1 —strictPASS0
check-count-consistency —strictPASS0
check-landing-page-counts —strictPASS0
check-workflow-generator-coveragePASS0
check-agents-md-command-syncPASS0
check-generated-content-untouchedPASS0
validate-mcp-syncPASS0
check-mcp-impactPASS (advisory)0

Cross-cutting findings

Section titled “Cross-cutting findings”

P1 findings

Section titled “P1 findings”

F-01: Deprecated reference to a removed skill path (deprecation tracking)

Section titled “F-01: Deprecated reference to a removed skill path (deprecation tracking)”

Location: library/skill-output-samples/develop-feature-spike/ (illustrative) Issue: A sample references skills/develop-feature-spike/SKILL.md, a skill directory deleted in a prior cycle. The path no longer resolves. Why it matters: Dead references break the docs link-validity gate and mislead users about the catalog. Fix: Repoint the sample to the surviving skill (develop-spike-summary), or delete the orphaned sample. Re-run check-internal-link-validity --strict.

F-02: Sample gap on dispatch skill utility-pm-skill-auditor

Section titled “F-02: Sample gap on dispatch skill utility-pm-skill-auditor”

Location: library/skill-output-samples/utility-pm-skill-auditor/ (does not exist) Issue: The newly shipped dispatch skill has no library samples in library/skill-output-samples/. Other utility skills (utility-pm-skill-builder, utility-pm-skill-validate, utility-mermaid-diagrams) have samples there. Why it matters: Discoverability and quality demonstration. New users land on the skill via docs site and look for samples; finding none reduces confidence. Fix: Author 1-3 library samples for this dispatch skill showing audit output against current repo state. Phase 6 task or v2.17 cleanup.

P2 findings

Section titled “P2 findings”

F-03: Description overlap between pm-critic dispatch skill and pm-skill-auditor dispatch skill (low risk)

Section titled “F-03: Description overlap between pm-critic dispatch skill and pm-skill-auditor dispatch skill (low risk)”

Location: skills/utility-pm-critic/SKILL.md description vs skills/utility-pm-skill-auditor/SKILL.md description Issue: Both descriptions begin with the dispatch-skill mechanism boilerplate (“Dispatches natively on Claude Code with the pm-skills plugin…”). The descriptions are distinct enough downstream that intent classifier should disambiguate, but the lead-in text is similar. Why it matters: Slight discoverability collision risk if Claude’s classifier matches on early-string similarity. Fix: Lead with the unique mission (“Run adversarial review on a PM artifact…” vs “Run a repo-wide cross-cutting governance audit…”) and put the dispatch mechanism in the second sentence. v2.17 cleanup acceptable.

F-04: Thread imbalance on pm-critic sub-agent samples (Phase 6 will resolve)

Section titled “F-04: Thread imbalance on pm-critic sub-agent samples (Phase 6 will resolve)”

Location: library/sub-agent-samples/pm-critic/ Issue: Only 1 of 3 planned samples shipped (brainshelf). Storevine and workbench samples are Phase 6 deliverables. Why it matters: Phase 6 closes this; not a defect, just an in-progress state. Fix: Phase 6 Task 23 ships the remaining 2.

Aggregate counter audit

Section titled “Aggregate counter audit”
SurfaceDeclaredRe-derivedMatch
Total skills5557NO (P2 - dispatch skills not yet in counters)
Phase skills2626YES
Foundation skills88YES
Utility skills68NO (P2 - 2 dispatch skills added in v2.16 Phase 2-3)
Tool skills1515YES
Sub-agents4 (planned)2EXPECTED (Phase 4-5 ship remaining 2)
Commands6264NO (P2 - 2 new commands utility-pm-critic utility-pm-skill-auditor not in declared count)
Workflows1212YES
Enforcing validators2727YES
Family contracts33YES

Counter notes: mismatch in skills/utility/commands columns is EXPECTED in-cycle. The mismatch reflects the in-progress nature of v2.16 (dispatch skills + new commands shipped in Phase 2-3 but declared counts in README/AGENTS still reflect v2.15.x baseline). These will reconcile during the pre-tag artifact pass (master plan Phase 8 equivalent) when README + AGENTS + CONTEXT.md get refreshed.

Disposition recommendations

Section titled “Disposition recommendations”
  • 0 P0 findings: clean to advance G0 gate (conductor would PASS)
  • 2 P1 findings: F-01 resolves automatically when Phase 5 ships; F-02 should be scheduled (Phase 6 or v2.17)
  • 2 P2 findings: F-03 cosmetic; F-04 in-progress (Phase 6 closes)
  • P3 findings hidden by —severity-floor P1

Status Summary

Section titled “Status Summary”

Pre-release audit at HEAD 00b3978 (post-Phase-2) returned 4 findings: 0 P0, 2 P1, 2 P2, 0 P3.

All 16 enforcing validators pass. No cross-cutting issues block ship. The two P1 findings are forward-looking: F-01 is a Phase 5 deliverable (will resolve when conductor ships); F-02 is a sample gap on the newly shipped dispatch skill (schedule for Phase 6 or v2.17). The two P2 findings are cosmetic or in-progress. The aggregate counter audit shows expected in-cycle drift between declared (v2.15.x baseline) and re-derived (v2.16 in-progress) counts; the pre-tag artifact pass will reconcile these.

Recommended next action: Continue with Phase 3-5 sub-agent authoring. No release-blocking issues. Re-run audit at end of Phase 5 to capture full slate.

Refusal triggered: no.

Status

Section titled “Status”
status: pass
p0_count: 0
p1_count: 2
p2_count: 2
p3_count: 0
counters_match: false
validators_pass: true
scope: full
refusal_reason: null


counters:
  declared:
    total_skills: 55
    sub_agents: 4
    commands: 62
    workflows: 12
    enforcing_validators: 27
  derived:
    total_skills: 57
    sub_agents: 2
    commands: 64
    workflows: 12
    enforcing_validators: 27


dispatch:
  mode: inline-execution
  client: cursor

Notes on This Example

Section titled “Notes on This Example”

The example shows a realistic mid-cycle audit (post-Phase 2 of v2.16.0). The findings reflect actual in-progress state: dispatch skills added, declared counts not yet reconciled (which is appropriate - counter reconciliation happens at pre-tag artifact pass, not at every phase boundary).

For a release-prep audit (post-Phase 5 + pre-tag), the same auditor would re-run after CONTEXT.md / AGENTS.md / README.md count refreshes; the counters_match field would flip to true; any remaining drift becomes P0 because at pre-tag scope, declared counts going to release notes must be correct.

Section titled “Related Files”