utility-pm-skill-auditor

$npx mdskill add product-on-purpose/pm-skills/utility-pm-skill-auditor

Run a repo-wide governance audit aggregating validators and cross-cutting checks.

  • Detects governance gaps no single validator catches.
  • Depends on pm-skill-auditor sub-agent or inline execution.
  • Reads CONTEXT.md, AGENTS.md, README.md to re-derive counters.
  • Outputs graded P0-P3 issues with machine-readable status.

SKILL.md

.github/skills/utility-pm-skill-auditorView on GitHub ↗
---
name: utility-pm-skill-auditor
description: Run a repo-wide cross-cutting governance audit via the pm-skill-auditor sub-agent. Aggregates the enforcing validator suite, re-derives aggregate counters, and surfaces cross-cutting issues no single validator catches, graded P0/P1/P2/P3 with a machine-readable status. Use for pre-release readiness checks or a periodic repo health audit.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.0.1"
  updated: 2026-06-10
  category: governance
  frameworks: [triple-diamond]
  author: product-on-purpose
---
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
# PM Skill Auditor (Dispatch Skill)

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

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

See [Sub-Agent Compatibility Matrix](../../docs/reference/sub-agent-compatibility.md) 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

- Canonical sub-agent definition: [`agents/pm-skill-auditor.md`](../../agents/pm-skill-auditor.md)
- Behavioral spec: [`docs/internal/release-plans/v2.16.0/spec_pm-skill-auditor.md`](../../docs/internal/release-plans/v2.16.0/spec_pm-skill-auditor.md)
- Runtime components catalog: [`docs/reference/runtime-components.md`](../../docs/reference/runtime-components.md)
- Cross-cutting check catalog: `docs/internal/release-plans/v2.16.0/spec_pm-skill-auditor.md#cross-cutting-check-catalog`
- Pre-tag validator bundle: `scripts/pre-tag-validate.{sh,ps1}`
- Output template: `references/TEMPLATE.md`
- Worked example: `references/EXAMPLE.md`

More from product-on-purpose/pm-skills

SkillDescription
define-hypothesisDefines a testable hypothesis with clear success metrics and a validation approach. Use when forming assumptions to test or aligning a team on what success looks like, before any experiment is designed. To design the A/B test or experiment that will validate the hypothesis, use measure-experiment-design.
define-jtbd-canvasCreates a Jobs to be Done canvas capturing the functional, emotional, and social dimensions of a customer job. Use when deeply understanding customer motivations, designing for jobs, or reframing product positioning.
define-opportunity-treeCreates an opportunity solution tree connecting a desired outcome to customer opportunities and candidate solutions, preventing solution-first jumps in continuous discovery. Use when structuring scattered feature ideas or communicating how the roadmap traces to outcomes. For ranking an existing flat list of candidates, use define-prioritization-framework instead; this skill discovers the list, it does not score one.
define-prioritization-frameworkRun applicable prioritization frameworks (RICE, ICE, MoSCoW, Weighted Scoring, Kano) against a list of features or initiatives. Produces a comparison table showing where rankings agree and diverge across frameworks, and an executive summary with recommendation. Framework applicability is filtered by data availability; Kano requires customer research. Refuses to fabricate scores; produces an estimation scaffold when input data is missing.
define-problem-statementCreates a clear problem framing document with user impact, business context, and success criteria. Use when starting a new initiative, realigning a drifted project, or communicating up to leadership.
define-xFixture skill for phase-map and phase-router tests.
deliver-acceptance-criteriaGenerates structured Given/When/Then acceptance criteria for a user story or feature slice, covering the happy path, key failure scenarios, and non-functional expectations in testable form. Use when turning requirements into verifiable scenarios for engineering handoff and QA sign-off. For a dedicated catalog of boundary conditions, error states, and recovery paths across a feature, use deliver-edge-cases; to write the stories themselves, use deliver-user-stories.
deliver-edge-casesDocuments edge cases, error states, boundary conditions, race conditions, and recovery paths for a feature - the systematic catalog of what can go wrong and the failure modes to design for. Use during specification to map the failure surface and ensure comprehensive coverage, or during QA planning to identify boundary and limit scenarios to test. Distinct from deliver-acceptance-criteria, which writes story-level Given/When/Then checks; this skill produces the whole-feature edge-case catalog.
deliver-launch-checklistCreates a cross-functional pre-launch checklist covering engineering, design, marketing, support, legal, and operations readiness, with owners, dates, and go/no-go criteria so nothing is missed before release. Use for significant or cross-team launches, not a small single-team change. For the customer-facing announcement of what shipped, use deliver-release-notes instead.
deliver-prdCreates a comprehensive Product Requirements Document that aligns stakeholders on what to build, why, and how success will be measured. Use when specifying features, epics, or product initiatives for engineering handoff.