write-product-spec skill (Warp): write PRODUCT.md behavior specs before you build

Warp's skill that makes your agent write a PRODUCT.md spec: a numbered list of testable behaviors for a feature, before any code.

Installs: 28.8K; on skills.sh
Stars: 644; on GitHub
Updated: Oct 2026; last repo commit

write-product-spec loads when you ask for a product spec, a desired-behavior doc or a PRD, or want to define behavior before building. Your agent gathers the feature summary, users, key behaviors and edge cases, asking you for anything missing, and asks whether a Figma mock exists for UI work.

It writes specs/<id>/PRODUCT.md with a short Summary and a long Behavior section of numbered invariants. It leaves out implementation details, validation and test plans, which belong in a TECH.md from the write-tech-spec skill. The text is written for Warp, but "user" is defined broadly: the person, code or developer who uses the thing being designed.

Good for

Product-minded engineers who want an agent to turn an idea into unambiguous behavior rules
Teams reviewing a feature plan in a pull request before building it
Anyone writing specs for an API, CLI or data model, not just a UI

Install write-product-spec

Claude Code

Copy this prompt.

Install the write-product-spec skill in Claude Code. Run this command:

npx skills add https://github.com/warpdotdev/common-skills --skill write-product-spec

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Write a PRODUCT.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation. Use when the user asks for a product spec, desired behavior doc, or PRD, wants to define feature behavior before implementation, or when the feature is substantial or behaviorally ambiguous enough that a written spec would improve implementation or review.

Sections in SKILL.md

Overview
Before writing
Figma mocks
Structure
The Behavior section
Length heuristic
Writing guidance
Keep the spec current
Related Skills
Example Behavior section
Behavior

Key facts

Author: Warp (warpdotdev/common-skills repo)
Installs on skills.sh: 28,795 as of 2026-11-02
GitHub stars: 644 for the whole common-skills repo, 2026-11-02
License: MIT (from GitHub repo data)
Last repo commit: 2026-10-28
Files: 1 file: SKILL.md only
Part of: Warp's common-skills repo, shared skills the README says may still contain Warp-specific wording

What it includes

Directory id, feature summary, users, behaviors, edge cases
Asks you for missing context instead of guessing, and for a feature name if there is no ticket.
Try: “Write a product spec for adding a dark-mode toggle to the settings screen.”
Read · Gather context
Asks if a mock exists; records the link or "Figma: none provided"
Read · Figma question
1 to 3 sentences on the feature and outcome
Write · Summary section
Numbered, testable invariants including edge and error states
Covers the happy path, every user-visible state, inputs, empty, error and loading states, cancellation, keyboard and accessibility expectations, and behaviors that must not regress.
Write · Behavior section
Problem, Goals / Non-goals, Figma, Open questions
Included only when they add signal. There is no Validation, Success criteria or Testing section; those live in TECH.md.
Write · Optional sections
specs/<id>/PRODUCT.md with a ticket, gh- issue or feature-name id
Write · Spec location
Uses Linear MCP tools or the gh CLI when you explicitly ask
Write · Create a ticket (on request only)

From the official docs

Permissions

Low risk

It writes one spec file in your repo and can create a ticket in Linear or GitHub if you ask. Check the team and repo before it files anything.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Ticket creation uses your accounts
If you ask for a new Linear ticket or GitHub issue, the agent uses the Linear MCP tools or gh with your login. Say which team, labels and repo to use. github.com

Technical details

Talks to	Linear or GitHub, only if you ask for a ticket
Scopes	Writes specs/<id>/PRODUCT.md in your repo Creates a Linear ticket or GitHub issue only when you explicitly ask

Questions

What does the write-product-spec skill do?

It makes your agent write a PRODUCT.md for a significant feature. The core is a Behavior section of numbered, testable rules from the user's point of view, with no implementation details.

How do I install it in Claude Code, the Claude app or Codex?

Use the install box at the top of this page. It is a single-file skill with no scripts.

Is it only for Warp?

Its wording says Warp, and its sample Behavior section is about rendering tables in Warp's block list. The method (numbered behavior invariants in specs/<id>/PRODUCT.md) does not depend on the Warp app, and the repo README says shared skills may still contain Warp-specific examples. SKILL.md also names a tool called ask_user_question for gathering missing context, which your agent may not have.

What is the next step after PRODUCT.md?

SKILL.md says to invoke the write-tech-spec skill for a TECH.md for the same feature, or to tell you that is the expected next step. Install write-tech-spec separately if you want it.

Does it create tickets for me?

Only if you explicitly ask. SKILL.md then uses the Linear MCP tools or the gh CLI. Otherwise it uses an id you give it or asks for a feature name.

How long should the spec be?

SKILL.md gives rough sizes: about 30 to 60 lines for a small feature and 80 to 150 for a medium one, with most length in the Behavior section. It says trivial fixes need no spec.

Information

updated Nov 2, 2026

Repository: warpdotdev/common-skills
Folder: .agents/skills/write-product-spec

warpdotdev/common-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

write-product-spec SKILL.md · github.com
common-skills README · github.com
skills.sh listing · skills.sh