product-specs-writer
Expert product specification and documentation writer. Use when creating PRDs, user stories, acceptance criteria, technical specifications, API documentation, edge case analysis, design handoff docs, feature flag plans, or success metrics. Covers the full spectrum from high-level requirements to implementation-ready specifications.
- Installs
- 213
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/ncklrs/startup-os-skills --skill product-specs-writer- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads product-specs-writer automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Product Specs Writer
Comprehensive product documentation expertise — from strategic PRDs to implementation-ready specifications that engineering teams can actually build from.
Philosophy
Great product specs bridge the gap between vision and execution. They're not bureaucratic documents; they're communication tools that align teams and prevent expensive misunderstandings.
The best product specifications:
- Start with the why — Context before requirements
- Are testable — Every requirement has clear acceptance criteria
- Anticipate questions — Edge cases, errors, and constraints documented upfront
- Evolve with the product — Living documents, not static artifacts
- Respect the reader — Engineers, designers, and stakeholders can all understand them
How This Skill Works
When invoked, apply the guidelines in rules/ organized by:
prd-*— Product Requirements Documents, vision, scopestories-*— User stories, personas, jobs-to-be-donecriteria-*— Acceptance criteria, definition of donetechnical-*— Technical specifications, architecture decisionsapi-*— API specifications, contracts, versioningedge-*— Edge cases, error handling, failure modesdesign-*— Design handoff, component specs, interactionsrollout-*— Feature flags, rollout plans, experimentsmetrics-*— Success metrics, KPIs, measurement plansmaintenance-*— Documentation lifecycle, versioning, deprecation
Core Frameworks
Specification Hierarchy
┌─────────────────────────────────────────┐
│ VISION │ ← Why are we building this?
│ (Problem & Opportunity) │
├─────────────────────────────────────────┤
│ PRD │ ← What are we building?
│ (Requirements & Constraints) │
├─────────────────────────────────────────┤
│ USER STORIES │ ← Who benefits and how?
│ (Personas & Journeys) │
├─────────────────────────────────────────┤
│ ACCEPTANCE CRITERIA │ ← How do we know it's done?
│ (Testable Conditions) │
├─────────────────────────────────────────┤
│ TECHNICAL SPECS │ ← How do we build it?
│ (Architecture & Implementation) │
└─────────────────────────────────────────┘
Document Types by Audience
| Document | Primary Audience | Purpose | Update Frequency |
|---|---|---|---|
| PRD | Leadership, PM, Design | Align on what and why | Per milestone |
| User Stories | Engineering, QA | Define scope and value | Per sprint |
| Acceptance Criteria | QA, Engineering | Define done | Per story |
| Technical Spec | Engineering | Define how | Per feature |
| API Spec | Frontend, External devs | Define contracts | Per version |
| Design Handoff | Engineering | Define UI/UX | Per component |
| Rollout Plan | Engineering, Ops | Define deployment | Per release |
| Success Metrics | Leadership, Data | Define success | Per quarter |
The INVEST Criteria (User Stories)
| Criteria | Question | Example |
|---|---|---|
| Independent | Can it be built alone? | No dependencies on unfinished stories |
| Negotiable | Is scope flexible? | Details can be refined with engineering |
| Valuable | Does user benefit? | Clear value proposition stated |
| Estimable | Can we size it? | Enough detail to estimate effort |
| Small | Fits in a sprint? | Can be completed in 1-5 days |
| Testable | Can we verify it? | Has clear acceptance criteria |
Specification Completeness Checklist
PRD Completeness:
├── Problem Statement □ Clearly defined user pain
├── Success Metrics □ Measurable outcomes defined
├── User Stories □ All personas covered
├── Scope □ In-scope and out-of-scope clear
├── Constraints □ Technical and business limits stated
├── Dependencies □ External dependencies identified
├── Risks □ Known risks and mitigations
├── Timeline □ Milestones and deadlines set
└── Open Questions □ Unknowns explicitly listed
Technical Spec Completeness:
├── Architecture □ System design documented
├── Data Model □ Schema and relationships defined
├── API Contracts □ Endpoints and payloads specified
├── Edge Cases □ Failure modes documented
├── Security □ Auth, encryption, compliance covered
├── Performance □ SLAs and benchmarks defined
├── Monitoring □ Observability strategy clear
└── Rollback Plan □ Recovery procedures documented
Error Handling Taxonomy
| Error Type | Example | Documentation Required |
|---|---|---|
| Validation | Invalid email format | Error message, field highlighting |
| Authorization | User lacks permission | Error state, escalation path |
| Resource | Item not found | Empty state, recovery action |
| System | Database timeout | Retry strategy, user feedback |
| Business Logic | Insufficient balance | Error explanation, next steps |
| External | Third-party API down | Fallback behavior, degraded mode |
Specification Templates
Minimal PRD Structure
# Feature: [Name]
## Problem
What user problem are we solving?
## Solution
High-level approach (1-2 paragraphs)
## Success Metrics
- Primary: [Metric] from X to Y
- Secondary: [Metric] from X to Y
## User Stories
- As a [user], I want [goal] so that [benefit]
## Scope
**In scope:** [List]
**Out of scope:** [List]
## Open Questions
- [ ] Question 1
- [ ] Question 2
User Story Template
**As a** [persona/user type]
**I want** [capability/action]
**So that** [benefit/value]
**Acceptance Criteria:**
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]
**Edge Cases:**
- What if [edge case]? Then [behavior]
**Out of Scope:**
- [Explicit exclusion]
Anti-Patterns
- Spec by committee — Over-collaboration produces vague documents
- Premature optimization — Specifying implementation details too early
- Missing the why — Requirements without context for decisions
- Kitchen sink scope — Trying to solve everything in one release
- One-way documentation — Specs that don't get updated as learnings emerge
- Assumption blindness — Not documenting implicit assumptions
- Designer/Engineer telephone — No direct communication, only docs
- Success theater — Metrics chosen because they're easy, not meaningful
- Spec as contract — Treating specs as unchangeable legal documents
- Documentation debt — Outdated specs worse than no specs
FAQ
What does the product-specs-writer skill do?
Expert product specification and documentation writer. Use when creating PRDs, user stories, acceptance criteria, technical specifications, API documentation, edge case analysis, design handoff docs, feature flag plans, or success metrics. Covers the full spectrum from high-level requirements to implementation-ready specifications.
How do I install product-specs-writer?
Run npx skills add https://github.com/ncklrs/startup-os-skills --skill product-specs-writer in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/product-specs-writer/ (personal) or .claude/skills/product-specs-writer/ (project).
Which AI agents can use product-specs-writer?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is product-specs-writer safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains product-specs-writer?
It is published by ncklrs in ncklrs/startup-os-skills. It has 213 recorded installs.
More from ncklrs/startup-os-skills
community-builder
ncklrs/startup-os-skills
Expert community-led growth and community management guidance. Use when building developer communities, Discord/Slack communities, online communities, managing community platforms, designing member onboarding, creating engagement programs, running ambassador programs, measuring community health, setting up moderation systems, or implementing DevRel strategies. Use for community-led growth, member activation, user-generated content programs, and community governance.
proposal-writer
ncklrs/startup-os-skills
Expert sales proposal and pricing presentation strategist. Use when writing proposals, executive summaries, ROI business cases, pricing presentations, SOWs (Statement of Work), RFP responses, or competitive positioning documents. Covers proposal structure, terms positioning, design formatting, follow-up strategy, and win-rate optimization.
motion-designer
ncklrs/startup-os-skills
Advanced motion designer with decades of After Effects and motion graphics experience, specialized in creating engaging video specifications for Remotion. Use when creating video specs, planning motion graphics, designing animations, or when asked to "create a video", "design motion graphics", "plan video content", or "spec out a video". Produces detailed scene-by-scene specifications with timing, audio, sound effects, and animation descriptions.
website-copy-specialist
ncklrs/startup-os-skills
Expert website copywriting for SaaS and B2B companies. Use when writing homepage copy, feature pages, about pages, pricing pages, comparison pages, product tours, integration pages, use case pages, demo/contact pages, or navigation microcopy. Use for website messaging hierarchy, value proposition development, and page-level conversion optimization.
vsl-storyboard-writer
ncklrs/startup-os-skills
Open the skill to read its SKILL.md instructions.
remotion-animation
ncklrs/startup-os-skills
Generates animation configurations for Remotion including spring configs, interpolations, easing functions, and timing logic. Focuses ONLY on animation parameters, NOT component implementation. Use when defining animation behavior or when asked to "configure animations", "setup spring configs", "define easing curves".
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.