User story writing
Skill timwukp/agent-skills-best-practice/skills/skills/user-story-writing
35 portable agent skills (Agent Skills spec) for Kiro & Claude Code: Scrum DevSecOps roles, PCI-DSS/MAS TRM compliance, AWS Well-Architected reviews — each with evals and a 4-layer tested methodology
npx -y skills add timwukp/agent-skills-best-practice --skill user-story-writingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Writes and refines user stories for product backlogs: splits epics into INVEST-compliant stories, drafts Given/When/Then and EARS-format acceptance criteria, and runs definition-of-ready checks. Triggers on: "write user stories", "split this epic", "acceptance criteria for", "refine this story", "is this story ready", "turn these requirements into stories".
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
3.9 KB, as published. Nobody here has run it
User Story Writing
Turn requirements, feature ideas, and epics into stories a team can estimate and deliver. The product is the story set, not prose about the feature.
Story Format
### [ID] [Title — verb phrase, outcome-oriented]
**As a** [specific user role — not "user"], **I want to** [action], **so that** [value the role actually cares about].
#### Acceptance Criteria
- Given [precondition], when [action], then [observable outcome]
- ...
For system-level or compliance-driven requirements where the persona format gets artificial, use EARS instead:
| EARS pattern | Template | Use for |
|---|---|---|
| Ubiquitous | The [system] shall [behavior] | Invariants |
| Event-driven | When [trigger], the [system] shall [behavior] | Responses to events |
| State-driven | While [state], the [system] shall [behavior] | Mode-dependent behavior |
| Unwanted behavior | If [undesired condition], then the [system] shall [behavior] | Error and abuse handling |
| Optional | Where [feature is included], the [system] shall [behavior] | Configurable capabilities |
INVEST Check
Run every story against INVEST before delivering; fix violations rather than annotating them:
- Independent — schedulable without forcing another story into the same sprint
- Negotiable — captures intent, not implementation; the "how" stays open
- Valuable — the "so that" names value for the role; "so that the database is updated" fails
- Estimable — a developer could size it; unknowns extracted into spike stories
- Small — fits comfortably in a sprint; otherwise split (see below)
- Testable — every criterion observable; "works correctly" fails
Epic Splitting Patterns
Apply the first pattern that yields shippable slices:
- By workflow step — each step of the user journey is a story (browse → select → pay → confirm).
- Happy path first — story 1 is the simplest successful flow; error handling, edge cases, and limits follow as separate stories.
- By business rule — base behavior first, each rule variation (discounts, regions, roles) its own story.
- By data variation — support one input type first (e.g. domestic transfers), add types incrementally.
- CRUD split — create first, then read/update/delete if each carries real value.
Never split by architectural layer — a "backend story" with nothing demonstrable is not a story.
Definition of Ready
A story is ready for sprint planning when:
- Acceptance criteria cover the happy path AND at least one failure/edge path
- Dependencies identified (other stories, external teams, data)
- Security consideration noted where the story touches auth, money, or personal data (one line; use the security-story-writing skill for dedicated security stories)
- UX reference attached where there's a user interface
- Team can estimate it without a meeting-length discussion
Guidelines
- Write criteria the QA engineer can execute verbatim. Vague criteria are deferred arguments.
- Keep the user role honest: if every story says "as a user", the personas were never real. Use the actual role names from the product.
- When given a batch of raw requirements, first group them into epics, present the grouping for confirmation, then split — don't generate 40 stories in one shot.
- Resist gold-plating: if a criterion doesn't trace back to the "so that", cut it.