OpenParable
Skip to content
← Back to skills

Writing User Stories

Productivity
writing-user-stories

Writing User Stories is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Creates INVEST-compliant user stories with acceptance criteria. Use when capturing requirements, defining backlog items, or breaking down features.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/design/writing-user-stories-jkappers-claude-code-software/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-user-stories, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

User Story Writing

Create user stories meeting INVEST criteria.

Execution Requirements

  1. Use templates/user-story.md template
  2. Validate against INVEST criteria before completing
  3. Include 2-5 acceptance criteria
  4. Replace all [bracketed placeholders]
  5. Assign Story ID using next sequential number

Mode Detection

CREATE: No existing story path → Copy template, generate next ID, fill sections

EDIT: Path provided → Read existing, preserve ID, update as requested

User Story Format

As a [type of user],
I want [goal/desire],
So that [benefit/value].

Example:

As a registered customer,
I want to save items to a wishlist,
So that I can purchase them later without searching again.

Required Elements

Title - Short, descriptive. "Wishlist - Add Items" not "User feature for saving stuff"

User Story Statement - Who (role), What (goal), Why (value)

Acceptance Criteria - Specific, testable conditions with Given-When-Then or checklist format

INVEST Criteria

CriterionMeaning
IndependentDevelop in any order
NegotiableDetails discussable
ValuableDelivers user/business value
EstimableTeam can size it
SmallFits in one sprint
TestableClear acceptance criteria

Acceptance Criteria Formats

Given-When-Then (preferred):

- [ ] Given [precondition], When [action], Then [result]

Checklist:

- [ ] User can [action with measurable outcome]

Writing Guidelines

Be specific about user roles: "premium subscriber" not "user"

Focus on outcomes: "export my data" not "a button"

State the benefit: "analyze in Excel" not "click it"

Story Splitting

Split large stories by: workflow steps, business rules, data variations, user roles, or CRUD operations.

Anti-Patterns

Do not write technical stories ("As a developer..."). Do not combine multiple features. Do not describe implementation. Do not omit the value clause. Do not use vague criteria.

Story vs Task vs Bug

TypePurpose
StoryNew user-facing capability
TaskTechnical work, no direct user value
BugFix broken behavior

Directory Structure

stories/
├── US-001-brief-description.md
├── US-002-brief-description.md
└── archive/

Create stories/ if needed. Scan for existing US-*.md files, find highest number, increment, pad to 3 digits.

Template

Use templates/user-story.md for all new stories.

Output

After creating/editing, report: file path, Story ID, acceptance criteria count, any INVEST concerns.