user-stories
Skill7 starsChanged 3 months agoMITView on GitHub
Write, split, and refine agile/scrum user stories and acceptance criteria. Produces /docs/STORIES.md as the canonical backlog, formatted to feed directly into the bdd-specs skill (Story → Feature, Given/When/Then acceptance criteria → Scenario/Specification). Use this whenever the user wants to write a user story, capture requirements as stories, "groom" or "refine" a backlog, break an epic or feature into stories, split a story that is too big, write or tighten acceptance criteria, draft a Definition of Done, or turn a vague feature request or PRD into a structured backlog — even if they don't say the words "user story" or "scrum".
23 other projects use a version of this.
Adopted by
Most recently taken up by
- Stijnus/dsh-rev-engtheir own version, first seen Nov 8, 2026
- daveebbelaar/bawatheir own version, first seen Nov 8, 2026
- yuusakuri/agent-skillstheir own version, first seen Nov 1, 2026
- shangyiy/life-kittheir own version, first seen Nov 1, 2026
- vijaysuperpositionist/skillstheir own version, first seen Nov 1, 2026
- Big-LAORE/Biblioth-que-de-skillstheir own version, first seen Nov 1, 2026
Used with
Projects with it also use brainstorm-experiments-new, brainstorm-experiments-existing and 10 more.
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.
skytiger6724Skillbrainstorm-experiments-new
Design lean startup experiments (pretotypes) for a new product. Creates XYZ hypotheses and suggests low-effort validation methods like landing pages, explainer videos, and pre-orders. Use when validating a new product idea, creating pretotypes, or testing market demand.
Also in 9 projects that use this
skytiger6724Skillbrainstorm-experiments-existing
Design experiments to test assumptions for an existing product — prototypes, A/B tests, spikes, and other low-effort validation methods. Use when validating assumptions, testing feature ideas cheaply, or planning product experiments.
Also in 7 projects that use this
45ckSkillpestle-analysis
Also in 7 projects that use this
About-IntelligenceSkillpositioning-ideas
Brainstorm product positioning ideas differentiated from competitors.
Also in 7 projects that use this
launchapp-devSkillinterview-script
Create a structured user interview script with warm-up, core exploration, and wrap-up sections. Use when preparing for user research interviews to ensure consistent, insightful conversations.
Also in 10 projects that use this
About-IntelligenceSkillproduct-name
Brainstorm 5 unique, memorable product names with rationale aligned to brand values and target audience.
Also in 7 projects that use this
- +6 more from skytiger6724
Other versions23 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 23
- daveebbelaar/bama★ 1.7ksame name
- Mehdibargach/claude-code-pm-skills★ 97same name
- daveebbelaar/bawa★ 17same name
- shangyiy/life-kit★ 10same name
- felipereisdev/user-stories-skill★ 9same name
- The-Utopia-Studio/skills★ 6same name
- gabriellst/codm★ 4same name
- JailtonJunior94/skills★ 4same name
- Adhamxon/claude-code-skills★ 2same name
- skytiger6724/qwen-skills★ 2same name
13 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-teamsSkill
- bdd-specsSkill
- design-principlesSkill
- githubSkill
- gof-patternsSkill
- onboardSkill
- postgres-dbaSkill
- security-webSkill
- solid-principlesSkill
- sqlite-devSkill
- typescript-best-practicesSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 2 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 22 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Write acceptance criteria as Given/When/Then from the start.
- Distinctive: line 47
What: do they want to do?
- Very specific: line 53
Ask the smallest number of questions that unblock you.
- Very specific: line 59
Use the canonical form. Read assets/STORIES.template.md for the exact file layout and copy its structure — it is what bdd-specs expects.
- Very specific: line 77
Keep one outcome per Then.
- Very specific: line 84
Before considering a story done, check it against INVEST and the smells list in references/invest-and-quality.md.
- Distinctive: line 87
Too big (not Small): If you cannot enumerate its acceptance criteria, or it spans multiple roles/outcomes, split it — see the splitting …
- Very specific: line 92
Not Testable: If you cannot phrase the acceptance criteria as Given/When/Then with observable outcomes, the story is underspecified.
- Very specific: line 127
Always write or update /docs/STORIES.md.
“Common” is measured: kept by at least 6 in 10 of the 22 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.
Files
User Stories
Turn product intent into a structured, testable backlog in /docs/STORIES.md. The
output is the input to the bdd-specs skill, so the structure here is not
cosmetic — it is a contract. Get the format right and stories flow into
executable specs and then code with no manual reshaping.
The pipeline you sit in
product intent ──▶ [user-stories] ──▶ /docs/STORIES.md ──▶ [bdd-specs] ──▶ spec files ──▶ codebdd-specs reads /docs/STORIES.md and /docs/PLAN.md and generates nested
specs: Feature > Scenario > Specification, where each Scenario arranges its
data once and every Specification makes exactly one assertion, happy paths first
and exhaustively, sad paths in their own block.
So map deliberately:
| Story artifact | Becomes in bdd-specs |
| One story | One Feature |
| One acceptance criterion | One Scenario |
| Given / When / Then steps | The Scenario's arrange / act / assert |
| Each distinct Then | One Specification (one assertion) |
| Happy-path criteria | Listed first, exhaustively |
| Error / edge criteria | A separate "sad path" group |
Write acceptance criteria as Given/When/Then from the start. That single habit is what makes the handoff clean.
Workflow
1. Establish context before writing
A story carries product knowledge the codebase does not. Do not invent the role, the goal, or the value. If the user hands you a vague feature ("add notifications"), interview rather than guess:
- Who is this for? (the role — be specific: "billing admin", not "user")
- What do they want to do?
- Why — what outcome or pain does it address? A story whose "so that" is hollow ("...so that I can use the feature") is usually a task, not a story.
- What does done look like? What must be observably true?
- What is explicitly out of scope for this story?
Ask the smallest number of questions that unblock you. If the user says "just
draft it and I'll correct it", do that — draft, mark assumptions with
> ASSUMPTION: lines, and let them react. Reacting is faster than specifying.
2. Write the story
Use the canonical form. Read assets/STORIES.template.md for the exact file
layout and copy its structure — it is what bdd-specs expects.
As a <specific role>,
I want <capability>,
so that <outcome / value>.Then acceptance criteria, each as a self-contained scenario:
AC1 — <short name>
Given <starting state>
When <action>
Then <single observable outcome>Keep one outcome per Then. If you need "and also", that is a second
criterion (it will become a second Specification downstream). Cover the happy
path exhaustively first, then error and edge criteria under a clearly separated
heading.
3. Quality-gate every story with INVEST
Before considering a story done, check it against INVEST and the smells list in
references/invest-and-quality.md. The two failures worth catching every time:
- Too big (not Small). If you cannot enumerate its acceptance criteria, or it spans multiple roles/outcomes, split it — see the splitting patterns in the reference. Prefer vertical slices (a thin end-to-end capability) over horizontal ones ("build the API", "build the UI"), because a vertical slice is independently valuable and testable.
- Not Testable. If you cannot phrase the acceptance criteria as Given/When/Then with observable outcomes, the story is underspecified. That is a signal to go back to step 1, not to lower the bar.
4. Epics and decomposition
An epic is a container, not a big story. Represent it as a heading that groups its child stories. Break an epic down only as far as the next sprint needs — near-term stories fully fleshed with acceptance criteria, later ones left as one-line placeholders. Over-decomposing a backlog that will change is waste (YAGNI applies to backlogs too).
5. Definition of Ready / Definition of Done
These are team agreements, so confirm them with the user rather than asserting
house rules. Capture them once at the top of STORIES.md (the template has a
slot). Default starting points are in the reference file; offer them, don't
impose them.
Scope boundaries
- In scope: writing stories, splitting/refining them, acceptance criteria, epic decomposition, Definition of Ready/Done, turning a PRD or feature request into a backlog.
- Out of scope, say so plainly: story-point estimation and sprint capacity planning are team rituals that depend on a specific team's history and velocity — a skill cannot do them credibly. Offer relative-size flags (S/M/L, or "this is too big, split it") instead of fabricated point numbers.
- Hand off, don't overlap: generating the executable specs from these
stories is
bdd-specs's job. Architecture/implementation planning is thePlanagent's or/docs/PLAN.md's job. Produce the backlog and point at the next step; don't do their work here.
Output
Always write or update /docs/STORIES.md. If it does not exist, create it from
assets/STORIES.template.md. If it exists, merge — preserve story IDs already
in use (downstream specs may reference them) and append or amend rather than
rewriting wholesale. After writing, tell the user how many stories/epics the
file now holds and that it is ready for bdd-specs.
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
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.

