Agent-Skills.md

Agent Skills: User Story

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.

UncategorizedID: mhylle/claude-skills-collection/user-story
12

Install this agent skill to your local

pnpm dlx add-skill https://github.com/mhylle/claude-skills-collection/tree/HEAD/skills/user-story

Skill Files

Browse the full folder contents for user-story.

Download Skill

Loading file tree…

skills/user-story/SKILL.md

Skill Metadata

Name
user-story
Description
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.

User Story

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")

| Scenario | Action | |----------|--------| | 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 brainstorms | Proceed to standalone mode (Phase 3) | | User selects a brainstorm | Read the file, proceed to Phase 2 | | User wants to start fresh | Proceed 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)

| Category | Example 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)

| Category | Example 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)

| Category | Example 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

| Level | Represents | Timeframe | Example | |-------|-----------|-----------|---------| | Epic | Major user capability | Weeks-months | "User Authentication" | | Feature | Deliverable functionality | Days-weeks | "Password Reset Flow" | | Task | Single implementable unit | Hours-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