agentleFS
mhyllemhylle/claude-skills-collection/skills/user-story/SKILL.md

user-story

Skill20 starsChanged 38 days agoMITView on GitHub

Generate hierarchical user stories (epics, features, tasks) with formal Given/When/Then acceptance criteria. Works from brainstorm output or standalone. Produces structured requirements that feed directly into create-plan. Triggers on "create user stories", "write stories", "define requirements", "user story", or when presenting features that need requirements decomposition.

19 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use review.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SentrySkill

    review

    Fixture review skill.

    Also in 4 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 17 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 18 edited versions we read keep these.

  • 17

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When this skill is invoked, respond:

    line 50
  2. Very specific:

    If the user passed a file path argument ($0):

    line 62
  3. Distinctive:

    If no argument provided, scan for recent brainstorm files:

    line 70
  4. Distinctive:

    Always check for existing stories to avoid duplication:

    line 84
  5. Distinctive:

    If existing stories overlap with the current scope, note them and ask whether to extend, revise, or create new epics.

    line 89
  6. Distinctive:

    After gathering context, present a summary:

    line 122
  7. Distinctive:

    When working without brainstorm input, use targeted Socratic questioning to understand requirements.

    line 135
  8. Distinctive:

    After each round, offer: "I have more questions if you'd like to continue refining, or we can move to story generation.

    line 165
  9. Distinctive:

    Do NOT rush -- thorough clarification produces better stories

    line 167
  10. Distinctive:

    Limits: If more than 5-7 epics emerge, discuss with the user which to prioritize for this session.

    line 185
  11. Distinctive:

    Before writing output, present the hierarchy for review:

    line 236
  12. Distinctive:

    Wait for user confirmation before proceeding to output.

    line 253
  13. Distinctive:

    Write the user story files following the conventions from ADR-0003 and ADR-0004.

    line 257
  14. Very specific:

    Write/update docs/user-stories/INDEX.md using the template from references/index-template.md.

    line 274
  15. Distinctive:

    After writing all files, present:

    line 278
  16. Distinctive:

    Before finalizing output, verify:

    line 313
  17. Distinctive:

    Users, not systems: Write from the user's perspective, not the system's

    line 338
  18. Distinctive:

    Testable: Every story should have clear, verifiable acceptance criteria

    line 340
  19. Very specific:

    Small enough: If a task has more than 3-4 Given/When/Then criteria, consider splitting it

    line 341
  20. Distinctive:

    When create-plan is invoked after user stories:

    line 360

“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

User Story

<!-- contents: generated by tests/skill_structure.py --write; edit headings, not this block -->

Contents

  • Overview
  • Initial Response
  • Workflow (5 Phases)
    • Phase 1: Input Detection
    • Phase 2: Context Gathering
    • Phase 3: Clarification (Standalone Mode)
    • Phase 4: Story Generation
    • Phase 5: Output
  • Shared Format Contract
  • Quality Checklist
  • Best Practices
    • Writing Good User Stories
    • Writing Good Acceptance Criteria
    • Hierarchy Guidelines
    • Integration with Create-Plan
  • Resources
    • references/

Reference files (open one when a step points to it):

  • references/index-template.md: User Stories Index Template
  • references/shared-format.md: Shared Format Contract: User Stories ↔ Create-Plan
  • references/story-template.md: User Story Epic File Template
<!-- /contents -->

Overview

This skill generates hierarchical user stories (epics → features → tasks) with formal Given/When/Then acceptance criteria. It works in two modes: consuming brainstorm output for rich context, or standalone with its own clarification phase. Task-level stories share format with create-plan phases for seamless handoff.

Workflow Position: brainstorm → (ADRs + user stories) → create-plan → implement-plan

Related ADRs:

  • ADR-0003: One file per epic with INDEX.md
  • ADR-0004: Hierarchical numbering (EPIC-NN.F-NN.T-NN)
  • ADR-0005: Shared format contract with create-plan
  • ADR-0006: Upstream of create-plan, parallel to ADRs

Initial Response

When this skill is invoked, respond:

"I'm ready to help you define user stories. I can work from a brainstorm document or start fresh. Let me check for recent brainstorms, or you can describe the feature/system you want to define requirements for."

Workflow (5 Phases)

Phase 1: Input Detection

Determine the input mode and gather initial context.

Step 1: Check for explicit brainstorm path

If the user passed a file path argument ($0):

Read($0)  # Read the brainstorm file

→ Proceed to Phase 2 with brainstorm content as context.

Step 2: Auto-scan for recent brainstorms

If no argument provided, scan for recent brainstorm files:

Glob("docs/brainstorms/*.md")
ScenarioAction
Recent brainstorms found (last 7 days)Present list and ask: "I found these recent brainstorms. Would you like to base user stories on one of them, or start fresh?"
No recent brainstormsProceed to standalone mode (Phase 3)
User selects a brainstormRead the file, proceed to Phase 2
User wants to start freshProceed to Phase 3

Step 3: Check for existing user stories

Always check for existing stories to avoid duplication:

Read("docs/user-stories/INDEX.md")  # If it exists

If existing stories overlap with the current scope, note them and ask whether to extend, revise, or create new epics.

Phase 2: Context Gathering

Gather all relevant context before generating stories.

Always do:

  1. Read brainstorm output (if available from Phase 1)
    • Extract: goals, components, risks, decisions, suggested scope
    • Identify user types/personas mentioned
  2. Read existing ADRs for architectural context:
    Read("docs/decisions/INDEX.md")
    # Then Quick Reference (first 10 lines) of relevant ADRs
  3. Read existing user stories INDEX (if it exists):
    Read("docs/user-stories/INDEX.md")

When project context is detected (user mentions codebase, files, modules):

  1. Research codebase for existing patterns:
    Task(subagent_type="codebase-locator",
         prompt="Find all files related to [feature area]")
    Task(subagent_type="codebase-analyzer",
         prompt="Analyze how [related functionality] is implemented")

After gathering context, present a summary:

## Context Summary
- **Source**: [Brainstorm file / Standalone input]
- **Existing Stories**: [None / EPIC-01, EPIC-02...]
- **Relevant ADRs**: [ADR-NNNN, ...]
- **Codebase Context**: [Key files and patterns found]

Then proceed to Phase 3 if standalone, or Phase 4 if brainstorm input provides sufficient context.

Phase 3: Clarification (Standalone Mode)

When working without brainstorm input, use targeted Socratic questioning to understand requirements.

Round 1: Users & Goals (ask 2-3 questions)

CategoryExample Questions
Users/Personas"Who are the primary users of this system/feature?"
"Are there different user roles with different needs?"
Core Goals"What is the primary problem being solved?"
"What does success look like for the user?"

Round 2: Scope & Constraints (ask 2-3 questions)

CategoryExample Questions
Scope"What is explicitly in scope for this work?"
"What should be considered out of scope?"
Constraints"Are there technical constraints to be aware of?"
"Are there existing systems this must integrate with?"

Round 3: Success Criteria (ask 2-3 questions)

CategoryExample Questions
Acceptance"How will you know this feature is working correctly?"
"What are the key scenarios that must work?"
Edge Cases"What error cases or edge cases concern you most?"
"What happens when things go wrong?"

Continuation Protocol:

  • After each round, offer: "I have more questions if you'd like to continue refining, or we can move to story generation. Your call."
  • Continue until user signals readiness
  • Do NOT rush -- thorough clarification produces better stories

Phase 4: Story Generation

Generate hierarchical user stories from the gathered context.

Step 1: Identify Epics

Extract high-level goals/capabilities from the input. Each epic represents a major user-facing capability.

Epic format:
  ID: EPIC-NN
  Title: [Capability name]
  Description: As a [user type], I want [goal] so that [benefit]
  Status: Draft

Limits: If more than 5-7 epics emerge, discuss with the user which to prioritize for this session.

Step 2: Decompose into Features

For each epic, identify 2-5 features that compose it:

Feature format:
  ID: EPIC-NN.F-NN
  Title: [Feature name]
  Description: As a [user type], I want [specific capability] so that [benefit]

Limit: Max 5 features per epic. If more emerge, suggest splitting the epic.

Step 3: Decompose into Tasks

For each feature, identify 2-5 implementable tasks:

Task format (shared with create-plan phases):
  ID: EPIC-NN.F-NN.T-NN
  Title: [Task name]

  **Objective**: [What this task accomplishes]

  **Acceptance Criteria**:
  - **Given** [precondition]
    **When** [action]
    **Then** [expected result]

  **Tasks** (tests first, then implementation):
  - [ ] Write tests: [test file] covering [scenarios]
  - [ ] Implement: [file] to make tests pass
  - [ ] Verify: [specific check or command]

  **Exit Conditions**:
  Build Verification:
  - [ ] [build/lint/typecheck commands]

  Runtime Verification:
  - [ ] [start command, no errors]

  Functional Verification:
  - [ ] [test commands, specific checks]

Limit: Max 5 tasks per feature. If more emerge, suggest splitting the feature.

Step 4: Review with User

Before writing output, present the hierarchy for review:

## Story Hierarchy Preview

### EPIC-01: [Title]
  - EPIC-01.F-01: [Feature title] (N tasks)
  - EPIC-01.F-02: [Feature title] (N tasks)

### EPIC-02: [Title]
  - EPIC-02.F-01: [Feature title] (N tasks)

Total: N epics, N features, N tasks

Does this decomposition look right? Any adjustments before I write the detailed stories?

Wait for user confirmation before proceeding to output.

Phase 5: Output

Write the user story files following the conventions from ADR-0003 and ADR-0004.

Step 1: Create directory (if needed)

mkdir -p docs/user-stories

Step 2: Write epic files

For each epic, write a file using the template from references/story-template.md:

File: docs/user-stories/EPIC-NN-slug.md

See references/story-template.md for the complete format.

Step 3: Create/update INDEX.md

Write/update docs/user-stories/INDEX.md using the template from references/index-template.md.

Step 4: Report summary

After writing all files, present:

## User Stories Created

| File | Epic | Features | Tasks |
|------|------|----------|-------|
| [EPIC-01-slug.md](docs/user-stories/EPIC-01-slug.md) | [Title] | N | N |
| [EPIC-02-slug.md](docs/user-stories/EPIC-02-slug.md) | [Title] | N | N |

**Index**: docs/user-stories/INDEX.md

## Recommended Next Steps
1. Review and refine acceptance criteria
2. Create ADRs for any architectural decisions identified (`/adr`)
3. Create implementation plan from these stories (`/create-plan`)

Shared Format Contract

Task-level stories share structure with create-plan phases per ADR-0005.

See references/shared-format.md for the exact contract.

Shared base (both user stories and plan phases):

  • Objective
  • Tasks (tests first, then implementation)
  • Exit Conditions (build/runtime/functional verification)

User stories add:

  • Acceptance Criteria (Given/When/Then)
  • Story description (As a [user], I want [goal] so that [benefit])

Quality Checklist

Before finalizing output, verify:

Structure:

  • All epics have Quick Reference blocks
  • Hierarchical numbering is consistent (EPIC-NN.F-NN.T-NN)
  • Max 5 features per epic, max 5 tasks per feature
  • INDEX.md is created/updated

Content:

  • Every story has "As a [user], I want [goal] so that [benefit]"
  • Every task has at least one Given/When/Then acceptance criterion
  • Task-level format matches shared format contract (Objective, Tasks, Exit Conditions)
  • Exit conditions cover build, runtime, and functional verification
  • Status is set (Draft for new stories)

Context:

  • Brainstorm input was fully consumed (if applicable)
  • Existing stories were checked for overlap
  • Relevant ADRs are referenced
  • User confirmed the hierarchy before output was written

Best Practices

Writing Good User Stories

  1. Users, not systems: Write from the user's perspective, not the system's
  2. Independent: Each feature should be independently deliverable where possible
  3. Testable: Every story should have clear, verifiable acceptance criteria
  4. Small enough: If a task has more than 3-4 Given/When/Then criteria, consider splitting it

Writing Good Acceptance Criteria

  1. Specific: "Given a user with admin role" not "Given a user"
  2. Observable: Focus on visible outcomes, not internal state
  3. Complete: Cover the happy path AND key error/edge cases
  4. Independent: Each criterion tests one behavior

Hierarchy Guidelines

LevelRepresentsTimeframeExample
EpicMajor user capabilityWeeks-months"User Authentication"
FeatureDeliverable functionalityDays-weeks"Password Reset Flow"
TaskSingle implementable unitHours-days"Email Validation on Reset Form"

Integration with Create-Plan

When create-plan is invoked after user stories:

  • Each task-level story can become a plan phase
  • Given/When/Then criteria become exit conditions
  • The shared format means no translation step is needed
  • Reference story IDs in the plan for traceability

Resources

references/

  • story-template.md - Epic file format and story structure at each level
  • index-template.md - INDEX.md template for user stories directory
  • shared-format.md - Shared format contract between user stories and create-plan

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.