ProductSpec skill
ProductSpec sets the format of a product spec, and its skills, CLI and MCP server guide an agent through it and check the result
- 317 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The CLI and MCP server run through `npx` and download `@productspec/parser@latest` from npm
- The `init` and `init-run` commands and the skills create and change spec and receipt files in the repository
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/productspecDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CLI and MCP server run through `npx` and download `@productspec/parser@latest` from npm
- The `init` and `init-run` commands and the skills create and change spec and receipt files in the repository
This is third-party code. Review the repository files before installing.
What it does
ProductSpec is an open standard for describing product intent: what to build, what not to build, how to prove it is done and when the plan changes. A spec lives in the repository as a `.product-spec.md` file with stable identifiers: `AC-` for acceptance criteria, `EVAL-` for model behavior checks and `SM-` for success metrics. The `spec_revision` number shows which version of the intent the agent took on. Two skills come with the standard. `productspec-authoring` writes a spec, converts an existing PRD into one and validates the result. `productspec` drives implementation from an existing spec: the agent finds `.product-spec.md` files, reads scope and criteria, stays inside `scope.in` and confirms before finishing that the spec has not changed. Next to them sit the `@productspec/parser` package with the `productspec` command (validate, handoff, graph, garden, reconcile, serve, mcp) and an MCP server with sessions such as `begin_spec_session` and `check_spec_session`. The result of an agent run is recorded in an Agent Run file with evidence links for every `AC-` and `EVAL-`, and deviations from the intent go into a Decision Trace. Validation can run in GitHub Actions, and a free browser editor, ProductSpec.io, writes specs without the CLI.
Who it is for. Product managers and teams that hand feature implementation to Claude Code, Codex or Cursor and want to check the result against written intent.
Good fit when
- A PRD or ticket describes the feature and the agent needs a verifiable spec with acceptance criteria
- CI has to check that `.product-spec.md` files are valid and evidence links are in place
- After code changes the agent must show evidence for every `AC-` criterion before reporting done
- Implementation runs into a deviation from the intent, and the decision is recorded in a Decision Trace
- Specs pile up in the repository, and `productspec garden` finds stale revisions and evidence gaps
Not a fit when
- The task is small and fits one message to the agent: a spec only adds paperwork
- You need a tool that judges the quality of a product decision itself: the standard defines structure and does not say what makes a spec good
- The team only needs an implementation plan for engineers: ProductSpec describes intent and the technical plan stays separate
- Node.js is missing: the CLI and MCP server run through npm
Example request
Use the productspec-authoring skill: convert docs/old-prd.md into docs/product-specs/checkout.product-spec.md and validate the fileLimitations
- The standard is neutral: it sets structure, section identifiers and the format of annotations, but does not define what makes a spec good.
- ProductSpec does not collect traces or run model behavior checks. It gives evidence a stable target, and the team maintains the links to results.
- The format is version 0.1 (`spec_format_version`), an early one, so the structure may change.
- The CLI and MCP server run through `npm exec` or `npx`, so Node.js and access to the npm registry are required.
How to disable. `npx skills remove productspec productspec-authoring` removes the skills. Delete the productspec entry from the MCP config, and the `.product-spec.md` files stay in the repository as ordinary Markdown.
FAQ
How do I install ProductSpec in Claude Code?
Run `npx skills add gokulrajaram/ProductSpec --all --full-depth`: it installs both skills, `productspec-authoring` and `productspec`. One skill is installed with `--skill <name>`. A file is checked with `npm exec --yes --package @productspec/parser -- productspec validate <file>`.
How do I connect the ProductSpec MCP server?
`npx --yes -p @productspec/parser@latest productspec mcp-config claude` prints a ready `mcpServers` block to paste into the Claude Desktop config. For Cursor use `cursor` instead of `claude`. Restart the client after editing.
How does ProductSpec differ from a PRD?
People read a PRD, while ProductSpec splits the text into parts with `AC-`, `EVAL-` and `SM-` identifiers that the agent and CI can check. The `productspec-authoring` skill converts an existing PRD into this format and keeps the author's intent.
What is an Agent Run?
It is a receipt file for one agent execution against a pinned spec revision: checked criteria, evidence links, drift status and the completion claim. `productspec init-run` creates a draft and `validate-run` checks it.
Is the ProductSpec.io editor required?
No, the standard works without it. The free browser editor helps write and validate a spec before commit, then export it to Markdown.
Discussion
No questions or reviews yet.
Related
SkillsTwo skills for spec-driven development: /spec asks questions and saves a document to specs/, /spec-impl implements an approved spec step by step
A CLI, MCP server and skill for spec-driven development: short markdown specs, a task board and search that an agent can read.
MCP server for spec-driven development: requirements, design and tasks step by step, with a web dashboard and a VS Code extension
Spec-driven development for coding agents: proposal, requirements, design and tasks come before any code
A CLI for spec-driven development: the agent carries a task through files in the repository from plan to verification and archive
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| ProductSpec (this card) | no | 317 | |
| Spec Kit | no | 148,171 | GitHub's spec-driven development kit with the specify command, while ProductSpec describes product intent and checks the agent's receipt against it |
| prd-taskmaster | no | 608 | turns a goal into a PRD and a task graph with execution, while ProductSpec sets the spec format and checks completion |
README in short
In the README ProductSpec is named an intent standard for agent-led work, followed by what agents can do with it and repository maintenance commands. It then covers linking intent to evidence, living specs, a quick start with a demo, guides for Claude Code, Cursor and Codex and MCP installation.
README badge
Original SKILL.md
--- name: productspec description: Use when implementing, reviewing, planning, or changing work governed by a Product Spec. Treat `.product-spec.md` files as the product contract for the work. --- # ProductSpec Agent Skill Product Specs are the product contract for consequential software work. When a repo uses Agent Run files, treat them as the receipt for one agent execution against a pinned Product Spec revision. Before planning, coding, testing, or changing scope, look for relevant `.product-spec.md` files in the repository. Common locations include: - `specs/` - `product-specs/` - `docs/product-specs/` - paths named in the task, issue, pull request, or engineering spec If a relevant Product Spec exists, read it before acting. ## How To Use A Product Spec Read these sections in order: 1. `Problem`: who is hurting and why the work matters. 2. `Hypothesis`: the causal bet behind the product. 3. `Product Summary`: what should exist when the work is done. 4. `Scope`: what is in, out, and deliberately cut. 5. `Acceptance Criteria`: the build contract, including AI evals when present. 6. `Success Metrics`: post-launch outcome checks. 7. `Related Artifacts`: issues, pull requests, eval runs, dashboards, designs, engineering specs, or other Product Specs the work depends on. Acceptance Criteria are the build contract. Plans, tasks, code changes, tests, and pull request summaries should cite the relevant `AC-<number>` IDs. AI evals are pre-launch gates inside Acceptance Criteria, not a separate `## AI Evals` section. Cite `EVAL-<number>` when implementing or changing model behavior. Success Metrics are post-launch outcomes. Do not treat `SM-<number>` items as implementation tasks. ## Planning Rules When creating an implementation plan: - List which Product Spec and `spec_revision` you are implementing. - If ProductSpec MCP is available, call `begin_spec_session` before planning and include the returned `spec_revision` and session id in your plan. - Map each task to the relevant Acceptance Criteria.