# User Story Writing

> Use when writing user stories, acceptance criteria, or breaking epics into shippable slices

- Skill: `kienbui1995/user-story-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kienbui1995/user-story-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kienbui1995/user-story-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kienbui1995 (https://skillmd.com/u/kienbui1995)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kienbui1995/user-story-writing

---


# User Story Writing

## When to Use
When translating requirements or product ideas into structured stories that dev teams can estimate and build.

## Core Jobs

### 1. Write the Story
Format: **As a** [user type], **I want** [action], **so that** [benefit]
- Be specific about the user type — not "user" but "free-tier customer" or "admin"
- The action should be observable behavior, not implementation detail
- The benefit connects to a business or user outcome

### 2. Define Acceptance Criteria
Use Given/When/Then for testable criteria:
- **Given** [starting context]
- **When** [action taken]
- **Then** [expected outcome]
Write 3–6 criteria per story. Each must be independently verifiable.

### 3. Size and Split
- Story should be completable in 1–3 days of dev work
- If larger: split by user type, happy path vs edge cases, or CRUD operation
- Never split by layer (frontend/backend) — that's a task, not a story

### 4. Definition of Done
Include in every story:
- [ ] Acceptance criteria pass
- [ ] Unit tests written
- [ ] Code reviewed
- [ ] Deployed to staging

## Key Outputs
- User story with role/action/benefit
- 3–6 Given/When/Then acceptance criteria
- Story sizing estimate (S/M/L or points)
- DoD checklist

## Anti-Patterns
- Stories written from system perspective ("The system shall...") — rewrite from user perspective
- Acceptance criteria that can't be tested
- Stories too large to complete in a sprint
- No benefit stated — if you can't explain why, don't build it