Skip to content
pm-skills

PM Skill Auditor (Dispatch Skill)

Quick facts

Classification: Utility | Version: 1.0.0 | Category: governance | License: Apache-2.0

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

  • 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

  • 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+)

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

Invoke @agent-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

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)

Output Template

Output Template

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

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)

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

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

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

Example Output

Example: pm-skill-auditor Dispatch on Cursor

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

cursor> /utility-pm-skill-auditor --scope full --severity-floor P1

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)

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

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

P1 findings

F-01: Sub-agent without companion command (sub-agent integrity, violates D6)

Location: agents/pm-release-conductor.md (does not yet exist as of HEAD; expected per master plan Phase 5) Issue: Phase 5 plan ships agents/pm-release-conductor.md paired with commands/pm-release.md. As of HEAD, neither exists. Once authored, ensure the pair lands in the same commit per agents/_pairing.yaml. Why it matters: D6 requires every sub-agent to ship with a companion slash command. Missing the command makes the sub-agent harder for users to discover. Fix: This is a forward finding (Phase 5 work). Re-run audit after Phase 5 ships; finding should resolve.

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

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)

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

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 /pm-critic /pm-audit-repo 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

  • 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

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

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

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.