Skip to main content
skill CX Codex

pm-spec-writing — Claude Code skill: turn ideas into specs

pm-spec-writing converts vague ideas and requests into clear briefs, PRDs, and bug reports that developers can build from. Clarifies what needs building before code starts.

MIT 286 installs ★ 1,107 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rampstackco/claude-skills --skill pm-spec-writing -a claude-code
Open on GitHub

What pm-spec-writing does

This skill transforms half-formed concepts into concrete development work. When a user says "I want to add", "we should build", or "how do we implement", the skill runs a four-phase structured process: first it clarifies the problem and success metric, then estimates scope against an impact-effort grid, then outputs a spec in one of three formats—full feature spec, lightweight dev brief, or bug report.

The framework works in four stages. Phase one asks the core questions: what problem does this solve, who benefits specifically, what's the success metric, why now. Phase two plots all candidate work on an impact-effort matrix to separate "ship immediately" from "skip indefinitely". Phase three writes the spec using the right template format, filling in acceptance criteria, dependencies, verify steps, and priority. Phase four breaks large work into smallest shippable increments. Every template includes required fields; blank sections are flags that the work is incomplete.

What it helps with

  • Convert a vague idea into an actionable dev brief
  • Write acceptance criteria and verify steps that developers interpret the same way
  • Prioritize a backlog and decide what to build first
  • File a bug report that someone else can reproduce immediately
  • Break a large initiative into separate shippable pieces

Example prompts for the agent

  • Write a feature spec: we need to export results to PDF with custom templates
  • Help prioritize: here's our feature backlog, score each one on impact vs. effort
  • Write a dev brief: add pagination to the /users API with default limit 20

How to install pm-spec-writing

1Skills CLI (Vercel)

npx skills add rampstackco/claude-skills --skill pm-spec-writing -a claude-code

2Manually: put the files in place

~/.claude/skills/pm-spec-writing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pm-spec-writing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pm-spec-writing

How do I install pm-spec-writing in Claude Code?

Run npx skills add rampstackco/claude-skills --skill pm-spec-writing -a claude-code, then check ~/.claude/skills/pm-spec-writing/SKILL.md to verify.

What does pm-spec-writing do?

It takes any idea or task and structures it into a complete specification. Asks about the problem, target users, success metric, picks the right format, and outputs a document that developers can build from without follow-up questions.

When should I use pm-spec-writing and when should I skip it?

Use it for new features, bugs, project scope, and backlog prioritization. Skip it for company-level strategy (roadmap-planning), code review (code-review-web), design decisions for existing features (design-standards), and user research (ux-research).

Source text

SKILL.md · MIT
---
name: pm-spec-writing
description: "Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks."
category: product
catalog_summary: "PRDs, user stories, acceptance criteria, dev briefs"
display_order: 1
---

# PM Spec Writing

Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work.

---

## When to use

- Translating an idea into a buildable feature spec
- Writing a PRD or product requirement document
- Filing a bug report that someone else can act on
- Scoping a project before kickoff
- Prioritizing a backlog of feature requests
- Writing acceptance criteria for an existing feature
- Breaking a large initiative into shippable increments

## When NOT to use

- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`)
- Code review or debugging existing code (use `code-review-web`)
- Design decisions for a feature already specced (use `design-standards`)
- User research to validate an idea (use `ux-research`)

---

## Required inputs

- The idea, request, or problem being addressed
- The audience or user affected
- Any existing constraints (stack, deadlines, dependencies)
- The success metric (how will you know it worked?)

If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness.

---

## The framework: 4 phases

Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary.

### Phase 1: Clarify the idea

Before any spec, answer four questions. If any answer is "I don't know," go back to the user.

1. **What user problem does this solve?** Not "what does it do." The problem comes first; the feature is the proposed solution.
2. **Who specifically benefits?** Be precise. "Users" is not specific. "First-time visitors who don't convert" is.
3. **What is the success metric?** How will you know it worked? Pick one primary metric.
4. **Why now?** What changed that makes this the right time to build it? If "nothing changed," it might not be the right time.

### Phase 2: Scope by impact and effort

Plot every candidate idea on the impact/effort grid:

```
HIGH IMPACT / LOW EFFORT       Ship immediately
  Examples: copy fixes, contrast fixes, meta tags,
            broken links, missing alt text, redirects

HIGH IMPACT / HIGH EFFORT      Plan and batch
  Examples: new page type, new feature, schema overhaul,
            major redesign, new integration

LOW IMPACT / LOW EFFORT        Nice-to-have batch
  Examples: tooltip improvements, minor copy polish,
            cosmetic UX touches

LOW IMPACT / HIGH EFFORT       Skip or defer indefinitely
  Examples: rebuilding what already works, exotic
            edge case features, premature optimization
```

This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions.

### Phase 3: Write the spec

Three formats based on the type of work.

#### Format A: Feature spec (for new features)

```
TITLE: [Specific, action-oriented]

PROBLEM
[1-2 sentences. The user problem and current state.]

USERS
[Who specifically benefits. Be precise about the user segment.]

PROPOSAL
[1 paragraph. The proposed solution. Stay at the conceptual level.]

USER STORIES
- As a [user type], I want to [action], so that [outcome]
- As a [user type], I want to [action], so that [outcome]

ACCEPTANCE CRITERIA
- Given [context], when [action], then [expected outcome]
- Given [context], when [action], then [expected outcome]

OUT OF SCOPE
[What this spec explicitly does NOT cover. Important for scope control.]

DEPENDENCIES
[Other systems, APIs, designs, content needed before this can ship.]

SUCCESS METRIC
[The one primary metric that tells us this worked. With current baseline if known.]

ESTIMATED EFFORT
[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)]

PRIORITY
[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog]
```

#### Format B: Dev brief (for handing to a developer or AI agent)

For tactical, ready-to-build work. Lighter than a full spec.

```
CONTEXT: [1-2 sentences explaining why this matters]

TASK: [Specific files, exact changes needed]

CONSTRAINTS: [What must NOT change, what to preserve]

VERIFY: [Exact steps to confirm the work is done correctly]
```

The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means.

#### Format C: Bug report

```
URL or context: [Where it happens]

Symptom: [What the user sees or experiences]

Expected: [What should happen instead]

Steps to reproduce:
1. [Specific step]
2. [Specific step]
3. [Specific step]

Hypothesis: [Likely root cause if known]

Files to investigate: [Likely files involved if known]

Priority:
  P0 - blocking critical user flow, ship immediately
  P1 - degrades UX significantly, fix this sprint
  P2 - minor issue, fix when convenient
  P3 - nice-to-have improvement

Browser/device: [If reproducibility might be browser-specific]
```

### Phase 4: Sequence and ship

Specs without sequencing become dust on a shelf.

For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate.

For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels.

---

## Workflow

1. **Clarify.** If the idea is vague, ask the four phase-1 questions before proceeding.
2. **Scope.** Plot the work on the impact/effort grid.
3. **Pick the right format.** Feature spec for new features, dev brief for tactical work, bug report for defects.
4. **Write the spec.** Use the template format. Fill in every section. Empty sections are flags.
5. **Define done.** Verify steps must be unambiguous. "Test it" is not a verify step.
6. **Get buy-in.** Walk through the spec with whoever will build it before they start.
7. **Sequence.** Identify the smallest shippable increment.

---

## Failure patterns

- **Specs that describe solutions before problems.** Always start with the user problem. The solution is downstream.
- **Specs without a success metric.** Without a metric, you cannot tell if the feature worked.
- **Acceptance criteria that are not testable.** "User experience is improved" is not testable. "User completes signup in under 60 seconds" is.
- **Specs that include the "how" instead of the "what."** Implementation details belong in the dev brief, not the spec. The spec is the desired outcome.
- **No "out of scope" section.** Without explicit boundaries, scope creeps.
- **Bug reports without reproduction steps.** Cannot be acted on. Always include steps.
- **Verify steps that are vague.** "Make sure it works." Useless. Must be specific actions with observable outcomes.
- **Skipping the smallest-shippable-increment exercise.** Leads to 6-month projects that should have been 2-week experiments.

---

## Output format

Output is one of three formats based on work type, all in markdown:

- `spec-[feature-name].md` for feature specs
- `brief-[task-name].md` for dev briefs
- `bug-[summary].md` for bug reports

For larger initiatives, group related specs in a folder:
```
specs/
  initiative-name/
    spec-feature-1.md
    spec-feature-2.md
    brief-task-1.md
    README.md   (overview and sequencing)
```

---

## If required data is unavailable

This skill's output depends on data, measurements, or tool results it cannot generate on its own. When a required input, tool, or data source is unavailable or unverifiable, the sanctioned output is the deliverable with the gap stated: what was needed, what was actually obtained or verified, and which parts of the output are affected. Fabricating, estimating, or interpolating a required number to complete the deliverable is never sanctioned. A stated gap is a complete answer.

---

## Reference files

- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template.
- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work.
- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW.

© rampstackco · MIT · rampstackco/claude-skills

Similar skills

All skills for Code review and refactoring →

From the same set102

The whole set →
seo-backlink-audit seo-backlink-audit reviews backlink quality via Ahrefs MCP: whether your profile is healthy, which links are risky, what you've lost, and how you stack against rivals. CX Codex +1 288installs seo-audit-orchestration seo-audit-orchestration runs a full SEO audit through Ahrefs MCP, coordinates focused checks, and turns their findings into one prioritized report. CX Codex +1 287installs seo-keyword-gap-audit The seo-keyword-gap-audit skill compares your site's organic footprint against competitors and flags keywords they rank for that you don't. Use it to plan content investment, spot quick wins, or scope market entry. CX Codex +1 287installs ai-content-collaboration ai-content-collaboration — a workflow guide for teams using AI in content production, with clear boundaries between model-assisted tasks and editorial decisions. CX Codex +1 287installs calculator-design The calculator-design skill helps plan ROI, pricing, savings, mortgage, and custom calculators. It focuses on useful decision support instead of hiding a weak result behind a lead form. CX Codex +1 286installs content-distribution content-distribution is a Claude Code skill for matching content and audiences to distribution channels. It addresses stalled reach and teams posting everywhere without a strategy. CX Codex +1 285installs experiment-design experiment-design is a skill for designing A/B tests, multivariate experiments, and holdouts so results answer the question being asked. CX Codex +1 285installs product-analytics-setup product-analytics-setup — a skill for instrumenting product analytics correctly through clean event taxonomies, property schemas, and funnels. It prevents untrusted metrics when shipping features. CX Codex +1 285installs

Project sponsors

Companies that keep this analytics open