{
  "schema": "https://ai-atoms.com/schemas/skill-v1.json",
  "type": "skill",
  "id": "skill/write-spec",
  "version": "1.0.0",
  "name": "write-spec",
  "description": "Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec.",
  "system_prompt_fragment": "# Write Spec\n\n> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).\n\nWrite a feature specification or product requirements document (PRD).\n\n## Usage\n\n```\n/write-spec $ARGUMENTS\n```\n\n## Workflow\n\n### 1. Understand the Feature\n\nAsk the user what they want to spec. Accept any of:\n- A feature name (\"SSO support\")\n- A problem statement (\"Enterprise customers keep asking for centralized auth\")\n- A user request (\"Users want to export their data as CSV\")\n- A vague idea (\"We should do something about onboarding drop-off\")\n\n### 2. Gather Context\n\nAsk the user for the following. Be conversational — do not dump all questions at once. Ask the most important ones first and fill in gaps as you go:\n\n- **User problem**: What problem does this solve? Who experiences it?\n- **Target users**: Which user segment(s) does this serve?\n- **Success metrics**: How will we know this worked?\n- **Constraints**: Technical constraints, timeline, regulatory requirements, dependencies\n- **Prior art**: Has this been attempted before? Are there existing solutions?\n\n### 3. Pull Context from Connected Tools\n\nIf **~~project tracker** is connected:\n- Search for related tickets, epics, or features\n- Pull in any existing requirements or acceptance criteria\n- Identify dependencies on other work items\n\nIf **~~knowledge base** is connected:\n- Search for related research documents, prior specs, or design docs\n- Pull in relevant user research findings\n- Find related meeting notes or decision records\n\nIf **~~design** is connected:\n- Pull related mockups, wireframes, or design explorations\n- Search for design system components relevant to the feature\n\nIf these tools are not connected, work entirely from what the user provides. Do not ask the user to connect tools — just proceed with available information.\n\n### 4. Generate the PRD\n\nProduce a structured PRD with these sections. See **PRD Structure** below for detailed guidance on what each section should contain.\n\n- **Problem Statement**: The user problem, who is affected, and impact of not solving it (2-3 sentences)\n- **Goals**: 3-5 specific, measurable outcomes tied to user or business metrics\n- **Non-Goals**: 3-5 things explicitly out of scope, with brief rationale for each\n- **User Stories**: Standard format (\"As a [user type], I want [capability] so that [benefit]\"), grouped by persona\n- **Requirements**: Categorized as Must-Have (P0), Nice-to-Have (P1), and Future Considerations (P2), each with acceptance criteria\n- **Success Metrics**: Leading indicators (change quickly) and lagging indicators (change over time), with specific targets\n- **Open Questions**: Unresolved questions tagged with who needs to answer (engineering, design, legal, data)\n- **Timeline Considerations**: Hard deadlines, dependencies, and phasing\n\n### 5. Review and Iterate\n\nAfter generating the PRD:\n- Ask the user if any sections need adjustment\n- Offer to expand on specific sections\n- Offer to create follow-up artifacts (design brief, engineering ticket breakdown, stakeholder pitch)\n\n## PRD Structure\n\n### Problem Statement\n- Describe the user problem in 2-3 sentences\n- Who experiences this problem and how often\n- What is the cost of not solving it (user pain, business impact, competitive risk)\n- Ground this in evidence: user research, support data, metrics, or customer feedback\n\n### Goals\n- 3-5 specific, measurable outcomes this feature should achieve\n- Each goal should answer: \"How will we know this succeeded?\"\n- Distinguish between user goals (what users get) and business goals (what the company gets)\n- Goals should be outcomes, not outputs (\"reduce time to first value by 50%\" not \"build onboarding wizard\")\n\n### Non-Goals\n- 3-5 things this feature explicitly will NOT do\n- Adjacent capabilities that are out of scope for this version\n- For each non-goal, briefly explain why it is out of scope (not enough impact, too complex, separate initiative, premature)\n- Non-goals prevent scope creep during implementation and set expectations with stakeholders\n\n### User Stories\nWrite user stories in standard format: \"As a [user type], I want [capability] so that [benefit]\"\n\nGuidelines:\n- The user type should be specific enough to be meaningful (\"enterprise admin\" not just \"user\")\n- The capability should describe what they want to accomplish, not how\n- The benefit should explain the \"why\" — what value does this deliver\n- Include edge cases: error states, empty states, boundary conditions\n- Include different user types if the feature serves multiple personas\n- Order by priority — most important stories first\n\nExample:\n- \"As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials\"\n- \"As a team member, I want to be automatically redirected to my company's SSO login so that I do not need to remember a separate password\"\n- \"As a team admin, I want to see which members have logged in via SSO so that I can verify the rollout is working\"\n\n### Requirements\n\n**Must-Have (P0)**: The feature cannot ship without these. These represent the minimum viable version of the feature. Ask: \"If we cut this, does the feature still solve the core problem?\" If no, it is P0.\n\n**Nice-to-Have (P1)**: Significantly improves the experience but the core use case works without them. These often become fast follow-ups after launch.\n\n**Future Considerations (P2)**: Explicitly out of scope for v1 but we want to design in a way that supports them later. Documenting these prevents accidental architectural decisions that make them hard later.\n\nFor each requirement:\n- Write a clear, unambiguous description of the expected behavior\n- Include acceptance criteria (see below)\n- Note any technical considerations or constraints\n- Flag dependencies on other teams or systems\n\n### Open Questions\n- Questions that need answers before or during implementation\n- Tag each with who should answer (engineering, design, legal, data, stakeholder)\n- Distinguish between blocking questions (must answer before starting) and non-blocking (can resolve during implementation)\n\n### Timeline Considerations\n- Hard deadlines (contractual commitments, events, compliance dates)\n- Dependencies on other teams' work or releases\n- Suggested phasing if the feature is too large for one release\n\n## User Story Writing\n\nGood user stories are:\n- **Independent**: Can be developed and delivered on their own\n- **Negotiable**: Details can be discussed, the story is not a contract\n- **Valuable**: Delivers value to the user (not just the team)\n- **Estimable**: The team can roughly estimate the effort\n- **Small**: Can be completed in one sprint/iteration\n- **Testable**: There is a clear way to verify it works\n\n### Common Mistakes in User Stories\n- Too vague: \"As a user, I want the product to be faster\" — what specifically should be faster?\n- Solution-prescriptive: \"As a user, I want a dropdown menu\" — describe the need, not the UI widget\n- No benefit: \"As a user, I want to click a button\" — why? What does it accomplish?\n- Too large: \"As a user, I want to manage my team\" — break this into specific capabilities\n- Internal focus: \"As the engineering team, we want to refactor the database\" — this is a task, not a user story\n\n## Requirements Categorization\n\n### MoSCoW Framework\n- **Must have**: Without these, the feature is not viable. Non-negotiable.\n- **Should have**: Important but not critical for launch. High-priority fast follows.\n- **Could have**: Desirable if time permits. Will not delay delivery if cut.\n- **Won't have (this time)**: Explicitly out of scope. May revisit in future versions.\n\n### Tips for Categorization\n- Be ruthless about P0s. The tighter the must-have list, the faster you ship and learn.\n- If everything is P0, nothing is P0. Challenge every must-have: \"Would we really not ship without this?\"\n- P1s should be things you are confident you will build soon, not a wish list.\n- P2s are architectural insurance — they guide design decisions even though you are not building them now.\n\n## Success Metrics Definition\n\n### Leading Indicators\nMetrics that change quickly after launch (days to weeks):\n- **Adoption rate**: % of eligible users who try the feature\n- **Activation rate**: % of users who complete the core action\n- **Task completion rate**: % of users who successfully accomplish their goal\n- **Time to complete**: How long the core workflow takes\n- **Error rate**: How often users encounter errors or dead ends\n- **Feature usage frequency**: How often users return to use the feature\n\n### Lagging Indicators\nMetrics that take time to develop (weeks to months):\n- **Retention impact**: Does this feature improve user retention?\n- **Revenue impact**: Does this drive upgrades, expansion, or new revenue?\n- **NPS / satisfaction change**: Does this improve how users feel about the product?\n- **Support ticket reduction**: Does this reduce support load?\n- **Competitive win rate**: Does this help win more deals?\n\n### Setting Targets\n- Targets should be specific: \"50% adoption within 30 days\" not \"high adoption\"\n- Base targets on comparable features, industry benchmarks, or explicit hypotheses\n- Set a \"success\" threshold and a \"stretch\" target\n- Define the measurement method: what tool, what query, what time window\n- Specify when you will evaluate: 1 week, 1 month, 1 quarter post-launch\n\n## Acceptance Criteria\n\nWrite acceptance criteria in Given/When/Then format or as a checklist:\n\n**Given/When/Then**:\n- Given [precondition or context]\n- When [action the user takes]\n- Then [expected outcome]\n\nExample:\n- Given the admin has configured SSO for their organization\n- When a team member visits the login page\n- Then they are automatically redirected to the organization's SSO provider\n\n**Checklist format**:\n- [ ] Admin can enter SSO provider URL in organization settings\n- [ ] Team members see \"Log in with SSO\" button on login page\n- [ ] SSO login creates a new account if one does not exist\n- [ ] SSO login links to existing account if email matches\n- [ ] Failed SSO attempts show a clear error message\n\n### Tips for Acceptance Criteria\n- Cover the happy path, error cases, and edge cases\n- Be specific about the expected behavior, not the implementation\n- Include what should NOT happen (negative test cases)\n- Each criterion should be independently testable\n- Avoid ambiguous words: \"fast\", \"user-friendly\", \"intuitive\" — define what these mean concretely\n\n## Scope Management\n\n### Recognizing Scope Creep\nScope creep happens when:\n- Requirements keep getting added after the spec is approved\n- \"Small\" additions accumulate into a significantly larger project\n- The team is building features no user asked for (\"while we're at it...\")\n- The launch date keeps moving without explicit re-scoping\n- Stakeholders add requirements without removing anything\n\n### Preventing Scope Creep\n- Write explicit non-goals in every spec\n- Require that any scope addition comes with a scope removal or timeline extension\n- Separate \"v1\" from \"v2\" clearly in the spec\n- Review the spec against the original problem statement — does everything serve it?\n- Time-box investigations: \"If we cannot figure out X in 2 days, we cut it\"\n- Create a \"parking lot\" for good ideas that are not in scope\n\n## Output Format\n\nUse markdown with clear headers. Keep the document scannable — busy stakeholders should be able to read just the headers and bold text to get the gist.\n\n## Tips\n\n- Be opinionated about scope. It is better to have a tight, well-defined spec than an expansive vague one.\n- If the user's idea is too big for one spec, suggest breaking it into phases and spec the first phase.\n- Success metrics should be specific and measurable, not vague (\"improve user experience\").\n- Non-goals are as important as goals. They prevent scope creep during implementation.\n- Open questions should be genuinely open — do not include questions you can answer from context.",
  "applicable_domains": [
    "product",
    "planning"
  ],
  "invocation": [
    "/write-spec",
    "/write-spec <feature or problem statement>"
  ],
  "tags": [
    "product-management",
    "anthropics",
    "knowledge-work"
  ],
  "authored_by": "anthropics",
  "source_url": "https://github.com/anthropics/knowledge-work-plugins/blob/main/product-management/skills/write-spec/SKILL.md",
  "lifecycle": "stable",
  "category": "product",
  "provenance": {
    "source": "anthropics/knowledge-work-plugins",
    "source_url": "https://github.com/anthropics/knowledge-work-plugins/blob/main/product-management/skills/write-spec/SKILL.md",
    "author": "Anthropic",
    "license": "Apache-2.0",
    "notes": "Imported by scripts/import-anthropic-skills.py."
  }
}