New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Write Product Spec

by warpdotdev in warpdotdev/common-skills

Write a PRODUCT.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation.

MITAuto-check passedProduct & Project Management

Install Write Product Spec

skills CLI
$ npx skills add warpdotdev/common-skills --skill write-product-spec -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install warpdotdev/common-skills write-product-spec --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/warpdotdev/common-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/write-product-spec .claude/skills/write-product-spec && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
write-product-spec
GitHub stars
608
Used in
1 other repo
Token cost
~3.3k tokens
SKILL.md length
1,273 words
Files
1
Skills in repo
28
Repo updated
First seen
Licence
MIT

At a glance

Write a PRODUCT.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation.

  • Works in 2 steps: Summary — 1–3 sentences describing the… → Behavior — The meat of the spec. An…
  • The user asks for a product spec
  • SKILL.md covers Overview, Before writing, Structure and The Behavior section, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Write Product Spec is an agent skill from warpdotdev/common-skills. 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.

Its SKILL.md is about 3.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Product & Project Management, covering PRD writing. The licence is MIT.

When your agent uses it

  • The user asks for a product spec
  • Desired behavior doc
  • Wants to define feature behavior before implementation
  • The feature is substantial

Example prompts

  • “/write-product-spec”

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. Summary — 1–3 sentences describing the feature and desired outcome.
  2. Behavior — The meat of the spec. An exhaustive English description of how the feature works, written as numbered, testable invariants. See…

What it can do on your machine

Read from SKILL.md and the folder at commit 2a03b40. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Write Product Spec loads about 3.3k tokens when it runs. Until then it costs about 98 tokens; SKILL.md has 1,273 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~98
When it runs · the whole SKILL.md, loaded when a task matches
~3.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from warpdotdev/common-skills at commit 2a03b40, republished under its MIT licence (© warpdotdev). 1,273 words, ~3,316 tokens.

Download SKILL.mdSave it as .claude/skills/write-product-spec/SKILL.md (or your agent's skills folder).
name
write-product-spec
description
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.

write-product-spec

Write a PRODUCT.md spec for a significant feature in Warp.

Overview

The product spec should make the desired behavior unambiguous enough that an agent can implement it correctly and avoid regressions. Describe the feature purely from the user's perspective — what the user sees, does, and experiences, and the invariants that must hold for them. Do not include implementation details (internal types, state layout, module boundaries, data flow, algorithms).

"User" is not limited to the end user of the Warp app. It means whoever consumes the surface being designed:

  • For UI / UX features: the human using Warp.
  • For a data model: the code that reads and writes that model.
  • For an API, protocol, or library: the callers of that API — other services, client code, plugins, or agents.
  • For a CLI tool or developer-facing surface: the developer invoking it.

The spec should describe behavior from that consumer's perspective: the shape of the surface, the operations they can perform, what they see back, invariants they can rely on, and edge cases they must handle — without prescribing how the surface is implemented underneath.

Implementation details, validation, and test planning live in a companion TECH.md, produced by the write-tech-spec skill. Writing the product spec is usually the first step of a two-step process: once PRODUCT.md is agreed on, invoke write-tech-spec to produce TECH.md for the same feature (or let the user know that's the expected next step). The product spec should be written so the tech spec can be written directly from it.

Write specs to specs/<id>/PRODUCT.md, where <id> is one of:

  • a Linear ticket number (e.g. specs/APP-1234/PRODUCT.md)
  • a GitHub issue id, prefixed with gh- (e.g. specs/gh-4567/PRODUCT.md)
  • a short kebab-case feature name (e.g. specs/vertical-tabs-hover-sidecar/PRODUCT.md)

specs/ should contain only id-named directories as direct children — no engineer-named subdirectories.

Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or gh CLI respectively (and ask_user_question if team, labels, or repo are unclear).

Before writing

Gather only the context you need: directory id (Linear ticket, GitHub issue, or feature name), feature summary, target users, key behaviors, edge cases, and how the feature will be validated. Use ask_user_question for missing context rather than guessing.

Figma mocks

If the feature has any UI or interaction design, ask the user whether a Figma mock exists before drafting the Behavior section, and include the link in the spec when one is provided. A mock is often the most reliable source of truth for visual states, spacing, and edge-case layouts — not asking can cause the Behavior section to guess at intent the designer already settled.

  • If the user provides a link, include it under a short ## Figma section (or inline near the top of Behavior) as Figma: <link>.
  • If the user confirms no mock exists, note Figma: none provided so the absence is explicit rather than ambiguous.
  • If the feature is purely backend (data model, API, CLI with no visual surface), skip the question and omit the section.

Do not silently drop design context; an explicit "none" is preferable to no mention at all on features where design would normally be expected.

Structure

Required sections:

  1. Summary — 1–3 sentences describing the feature and desired outcome.
  2. Behavior — The meat of the spec. An exhaustive English description of how the feature works, written as numbered, testable invariants. See "The Behavior section" below — this is where the spec earns its length, and everything else should stay thin to avoid duplicating it.

Optional sections — include only when they add signal beyond the core. Omit the heading entirely if empty; do not write "None" as a placeholder.

  • Problem — Include only when the motivation isn't obvious from Summary.
  • Goals / Non-goals — Include when scope is ambiguous or has been contested.
  • Figma — Include with a link when one exists, or an explicit Figma: none provided note when design matters but no mock exists. Omit entirely for non-visual features. See "Figma mocks" above.
  • Open questions — Prefer inline **Open question:** … next to the relevant behavior. Include a dedicated section only if there are multiple unresolved questions worth collecting.

Do not include Validation, Success criteria, or Testing sections. Validation and test planning live in the companion TECH.md (produced by write-tech-spec). Write Behavior as numbered invariants that are testable on their own — the tech spec can reference them directly.

Show full SKILL.md (522 more words)Show less

The Behavior section

Behavior is the spec. Everything else is framing.

The goal of Behavior is a complete English description of how the feature works, detailed enough that a tech spec can be written directly from it without the author having to guess or re-derive product intent. If a reader finishes Behavior with questions about what the feature does in some situation, the section is not done.

Describe, at minimum:

  • Default behavior and the happy-path user flow.
  • Every user-visible state and the transitions between them.
  • All inputs the user can provide and how the feature responds.
  • Empty states, error states, loading / pending states, and cancellation.
  • Edge cases a reasonable implementer would not think to ask about — permission denied, offline, timeouts, races between state changes, multiple concurrent instances, stale or missing data, focus loss mid-interaction, interactions with adjacent features.
  • Keyboard, accessibility, and focus expectations where relevant.
  • Invariants that must hold at all times and behaviors that must not regress.

Length Behavior to match the feature. Trivial features may need a handful of invariants; complex features may need many, with sub-sections per flow or state. The rest of the spec should stay thin so Behavior can be as exhaustive as the feature requires without producing a bloated document overall. Err toward enumerating one more edge case rather than one fewer.

Length heuristic

Behavior should be as long as the feature requires — do not truncate edge cases to hit a line target. The heuristic below applies to everything around Behavior (Summary, optional sections): keep that framing thin so the spec's total length reflects the feature's actual complexity, not structural overhead.

  • Trivial fix or narrow UI tweak: no spec.
  • Small feature (single module, few edge cases): framing plus Behavior typically ~30–60 lines total.
  • Medium feature (cross-module, multiple states): typically ~80–150 lines total.
  • Large or behaviorally rich feature: longer is fine, and most of the length should live in Behavior.

If you find yourself writing the same idea in Summary, Problem, Goals, and Behavior, collapse the framing — not the Behavior content.

Writing guidance

  • Prefer concrete, observable behavior over aspirational wording.
  • Write Behavior as a list of invariants rather than prose when possible.
  • Capture invariants that must not regress and edge cases that are easy to miss.
  • Avoid implementation details unless unavoidable for the UX.
  • Each section should earn its place — if a section would repeat another or contain only boilerplate, omit it.

Keep the spec current

Approved specs may ship in the same PR as the implementation. As implementation evolves, update PRODUCT.md in the same PR when user-facing behavior or UX details change. The checked-in spec should describe the feature that actually ships.

For large features, the implementer may optionally keep a DECISIONS.md file summarizing concrete decisions made during design and implementation. Offer it when it would help future agents; otherwise skip it.

  • implement-specs
  • write-tech-spec
  • spec-driven-implementation

Example Behavior section

A sample Behavior section for a hypothetical feature: rendering GitHub-flavored Markdown tables in the Warp block list. It demonstrates the expected shape — numbered, testable, user-perspective invariants that enumerate defaults, edge cases, malformed input, streaming, selection/copy, search, sharing, theming, and cross-surface consistency, with one inline open question.

markdown
## Behavior

1. When a terminal output block contains a GitHub-flavored Markdown table (a header row, a separator row of one or more `---` segments, and one or more body rows, all delimited by `|`), that table renders as a visually formatted table in the block — not as raw pipe-delimited text.

2. The table renders with:
   - A visually distinct header row.
   - Aligned columns based on the separator row: `|:---|` left-align, `|:---:|` center, `|---:|` right-align. `|---|` with no colons falls back to the default alignment (left for text, right for numeric-looking values).
   - Visible row separators (or equivalent spacing) consistent with the active theme.

3. Inline markdown inside a cell renders inline: bold, italic, inline code, strikethrough, and links all render the same way they do in the surrounding block output. Line breaks inside a cell (`<br>` or escaped `\n`) render as in-cell line breaks.

4. Column widths are chosen to fit the table's natural content when it fits inside the block. If a single cell's content is very long, that cell wraps its text within its column rather than forcing the column to an unreasonable width.
   - **Open question:** when a wrapped cell would produce an unreasonably tall row, do we clip with an "expand" affordance, or let the row grow unbounded?

5. Horizontal scrolling: when the table's total width exceeds the block width — many columns, or wide columns that can't reasonably be narrowed — the table becomes horizontally scrollable within the block. Scrolling horizontally reveals off-screen columns without clipping or truncating them. Vertical scrolling of the block continues to work independently of table scroll.

6. When the block is resized (terminal resize, pane split, sidebar open/close), the table reflows to the new width without losing row or column order.

7. Empty cells render as visibly empty (same row height as surrounding cells, no placeholder text). A row with all empty cells still renders as a row.

8. A table with only a header and separator (zero body rows) renders as a header-only table, not as raw text.

9. A single-column table renders as a single-column table (not collapsed to a bullet list or similar).

10. Malformed tables fall back gracefully:
    - Missing separator row → rendered as preformatted text, not as a table.
    - Ragged rows (some rows have fewer or more cells than the header) → missing cells render empty; extra cells are shown, with the header row extended visually if possible. The block should never silently drop data.
    - Unclosed table (last row truncated mid-stream) → rendered as a partial table; see (11).

11. Streaming output: while a command is still producing rows, the table renders incrementally. New rows append as they arrive. The header row locks in as soon as the separator line is received; rows before the separator render as plain text until the table is recognized.

12. Selection and copy:
    - Selecting across cells with the mouse or keyboard selects their visible text content.
    - Copying the selection produces tab-separated plain text by default (one row per line, cells separated by tabs). An affordance (context menu, shortcut) lets the user copy the original markdown source instead.
    - Copying the entire block preserves the original markdown source verbatim.

13. Search within a block (find-in-block) matches against cell text content. Matches highlight in place in the rendered cell; navigating matches scrolls the table into view, including horizontally if the match is in an off-screen column.

14. Sharing or exporting a block (Warp Drive, share link, save as file) preserves the original markdown source, not the rendered form.

15. Theming: table borders, header backgrounds, alternating row shading (if any), and link/code styles all come from the active Warp theme. No hard-coded colors.

16. Markdown tables render consistently wherever block-list markdown already renders — command output, agent responses, and any other block type that supports inline markdown. The same input produces the same table in each surface.

17. Non-table pipe content is not misrendered as a table. Text that contains `|` characters but no valid header-separator line remains plain text, even if it visually resembles a table.

© warpdotdev, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/write-product-spec of warpdotdev/common-skills.

Open the folder on GitHubat commit 2a03b40

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in warpdotdev/common-skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Write Product Spec next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Write Product Spec compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Write Product Spec this skillwarpdotdev/common-skills6081 repos~3.3kAutomated safety check: PassMIT
CCPM Project Managementautomazeio/ccpm8.4k—~1.1kAutomated safety check: PassMIT
Ralph Tui Create Beadssubsy/ralph-tui2.5k1 repos~2.6kAutomated safety check: PassMIT
Trellis Brainstormanjiemo/SunnyBeach1787 repos~4kAutomated safety check: PassApache-2.0
Adversarial Speczscole/adversarial-spec5561 repos~8.3kAutomated safety check: NotesMIT
Ralph Tui Create Beads Rustsubsy/ralph-tui2.5k1 repos~2.8kAutomated safety check: PassMIT

Similar skills

  • CCPM Project Management

    automazeio/ccpm

    Runs a spec-driven workflow from PRD to epic to GitHub issues to parallel agents, with status, standup and blocked-work reports from bundled scripts.

    8.4k GitHub stars~1.1k tokensUpdated 6 mo ago
    Product & Project ManagementAuto-check passed

  • Ralph Tui Create Beads

    subsy/ralph-tui

    Convert PRDs to beads for ralph-tui execution. An agent skill from subsy/ralph-tui.

    2.5k GitHub starsUsed in 1 repo~2.6k tokens
    Product & Project ManagementAuto-check passed

  • Trellis Brainstorm

    anjiemo/SunnyBeach

    Guides collaborative requirements discovery before implementation.

    178 GitHub starsUsed in 7 repos~4k tokens
    Product & Project ManagementAuto-check passed

  • Adversarial Spec

    zscole/adversarial-spec

    Iteratively refine a product spec by debating with multiple LLMs (GPT, Gemini, Grok, etc.) until all models agree.

    556 GitHub starsUsed in 1 repo~8.3k tokens
    Product & Project ManagementAuto-check: notes

  • Ralph Tui Create Beads Rust

    subsy/ralph-tui

    Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI).

    2.5k GitHub starsUsed in 1 repo~2.8k tokens
    Product & Project ManagementAuto-check passed

  • Ouroboros PM Interview

    Q00/ouroboros

    Runs a guided product-manager interview that classifies each question automatically and produces a Product Requirements Document.

    6.2k GitHub starsUsed in 1 repo~5.7k tokens
    Product & Project ManagementAuto-check passed

More from warpdotdev/common-skills

All 28 skills in this repo

  • Skill Doctor

    warpdotdev/common-skills

    Grades agent skills by scoring agent conversations for efficiency, code quality, procedure compliance, and verbosity, then drafts concrete skill edits and a shareable report.

    608 GitHub starsUsed in 2 repos~2.6k tokens
    Auto-check passed

  • Readout

    warpdotdev/common-skills

    Produce a polished, self-contained HTML "readout" document under ~/.readouts (with an auto-maintained index page), either by snapshotting the findings accumulated in the current conversation or —…

    608 GitHub stars~2k tokensUpdated today
    Auto-check passed

  • Resolve Merge Conflicts

    warpdotdev/common-skills

    Resolve Git merge conflicts by extracting only unresolved paths, conflict hunks, and compact diffs instead of loading whole files into context.

    608 GitHub stars~733 tokensUpdated today
    Auto-check passed

  • Review PR

    warpdotdev/common-skills

    Review a pull request diff and write structured feedback to review.json for the workflow to publish.

    608 GitHub stars~2.6k tokensUpdated today
    Auto-check passed

  • Saga

    warpdotdev/common-skills

    Run an autonomous, spec-driven development "saga" for medium-to-large features using an orchestrator agent and a fleet of worker subagents.

    608 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • PR Walkthrough

    warpdotdev/common-skills

    Generate a static interactive D3 walkthrough of a pull request.

    608 GitHub starsUsed in 1 repo~7.2k tokens
    Auto-check passed

Categories

Questions about Write Product Spec

What does Write Product Spec do?

Write a PRODUCT.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation. Write Product Spec is an agent skill from warpdotdev/common-skills.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation.

When should I use Write Product Spec?

Write Product Spec fits situations like: the user asks for a product spec; desired behavior doc; wants to define feature behavior before implementation; the feature is substantial.

How do I install Write Product Spec in Claude Code?

Run `npx skills add warpdotdev/common-skills --skill write-product-spec -a claude-code`. Or copy the skill folder (.agents/skills/write-product-spec in warpdotdev/common-skills) into .claude/skills/write-product-spec in your project. Claude Code loads it when a task matches its description.

How do I install Write Product Spec in Codex?

Run `npx skills add warpdotdev/common-skills --skill write-product-spec -a codex`. Or copy the skill folder (.agents/skills/write-product-spec in warpdotdev/common-skills) into .agents/skills/write-product-spec in your project. Codex loads it when a task matches its description.

Can I use Write Product Spec in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add warpdotdev/common-skills --skill write-product-spec -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/write-product-spec, .gemini/skills/write-product-spec, .github/skills/write-product-spec and .opencode/skills/write-product-spec in your project.

What does Write Product Spec need to run?

SKILL.md names no scripts, command-line tools or credentials: Write Product Spec is instructions for the agent only.

Does Write Product Spec access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Write Product Spec safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Write Product Spec use?

Write Product Spec is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Write Product Spec use?

About 3.3k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Write Product Spec?

Skills that share tags, products or a category with Write Product Spec: CCPM Project Management (automazeio/ccpm, 8.4k stars), Ralph Tui Create Beads (subsy/ralph-tui, 2.5k stars), Trellis Brainstorm (anjiemo/SunnyBeach, 178 stars) and Adversarial Spec (zscole/adversarial-spec, 556 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Write Product Spec?

warpdotdev (a GitHub organization) maintains it in warpdotdev/common-skills, which has 608 GitHub stars. The repository holds 28 skills in this directory. The repository was last updated on October 7, 2026.

Source: warpdotdev/common-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.