pm-skills

A senior PM's review of your brief, inside Claude Code and Codex.

Ask an AI to review your brief and it tells you it's good. Push back and it agrees with that too.

pm-skills is for product managers. It reads your draft the way a senior PM would and holds its position when you argue.

It ranks the problems, then helps you draft the fixes. Free and open source.

Install pm-skillsSee an example

01What it checks

A second opinion on the things AI tends to miss.

The case:
Audience, problem, evidence, assumptions and connection to a product outcome.
The plan:
Scope, dependencies, trade-offs, success measures and missing failure behaviour.
The argument:
Contradictions, unsupported claims and questions the intended reader will ask.
The writing:
Vague language, padding, AI phrasing and whether the point comes across.

The review uses PM guidance for your document type and takes relevant stakeholder perspectives. Use it on briefs, specs, strategies, roadmaps, metrics, retros and messages.

02How the review works

  1. Frame

    Establish the document, audience and product context.

    Your document
    +
    context

  2. Critique

    Apply PM checks, ask reader questions and rank the findings.

    Findings
    • P0
    • P1
    • P2
    • Writing
    After you agree

  3. Refine

    Draft targeted fixes after you agree.

    Proposed fixes
Substantive findings are ranked P0, P1 or P2. Writing issues are reported separately. You get an overall verdict and the changes needed to improve it.

03Example review

A feature brief going to engineering. Fictional input; PM review recorded in Claude Code.

The review rated it ROUGH. This is one of the findings.

Draft

  • When the request completes, show “Projects archived” and remove archived projects from the active list.
  • If any projects fail, show a general error and keep the selection so the user can try again.

The supplied context says the request can succeed for some projects and fail for others.

P0: fix before implementation

The partial-failure state is contradictory and breaks the brief's own success criterion.

The AI's first draft assumed everything would succeed. The review pushed harder and asked what happens if the riskiest parts fail, then proposed and drafted a fix.

For this demo, Codex wrote the fictional brief and supplied the follow-up product decisions, including how to report each result.

From the proposed fix, drafted by pm-skills

The full fix includes per-result behaviour and retry rules. This is the summary rule:

After every completed request, show a summary that states three counts: newly archived, already archived, and not archived. Never show the unqualified message “Projects archived” when any project was not archived.

Read the complete example

04Install

You'll need access to Claude Code or Codex.

Claude Code

Run these in Claude Code:

/plugin marketplace add jameshemson/pm-skills
/plugin install pm@pm-skills

If Claude Code asks you to reload plugins, do that before running the review.

Then review a draft:

/pm:pm review path/to/brief.md

Codex

Run these in your terminal:

codex plugin marketplace add jameshemson/pm-skills
codex plugin add pm@pm-skills

Then enter this in Codex:

$pm:pm review path/to/brief.md

Replace the path with your own document. If product context isn't set up, pm-skills asks whether to save it or use context for this session.

05Reference

Replace review in the command above with another mode name, followed by the work you want it to do.

review:
Review a document and prioritise its problems.
teach:
Save product context for later work.
setup:
Turn team norms into project instructions.
brief:
Draft a brief for its intended audience.
spec:
Write a specification with scope, risks and measures.
stories:
Write user stories with testable acceptance criteria.
metrics:
Work out what to measure, then set guardrails and counter-metrics.
decide:
Compare options and make the trade-offs explicit.
discover:
Plan customer interviews or review what you learned.