user-story
by deanpetersThe user-story skill helps you turn product needs into a single, development-ready story with Mike Cohn wording and Gherkin acceptance criteria. Use it for clearer handoffs, better estimation, and a tighter user-story guide for Technical Writing and product teams.
This skill scores 84/100, which means it is a solid listing candidate for directory users who want a focused user-story builder. The repository gives enough trigger language, formatting guidance, and example output to help an agent use it with far less guesswork than a generic prompt, though it is not yet a fully polished, end-to-end workflow package.
- Clear trigger and intent: 'Create user stories with Mike Cohn format and Gherkin acceptance criteria' plus 'Use when' guidance makes invocation straightforward.
- Operationally useful structure: the template, examples, and rules for one When/Then pair give agents a concrete output shape to follow.
- Extra execution support: the included Python script and repeatable 'Given' inputs improve repeatability and reduce formatting ambiguity.
- No install command or package metadata, so users may need to wire it into their own workflow manually.
- Documentation is strong on formatting but lighter on edge cases, validation rules, or guidance for splitting stories beyond a brief note.
Overview of user-story skill
The user-story skill helps you turn a rough product need into a single, development-ready user story with Mike Cohn wording and Gherkin acceptance criteria. It is best for product managers, technical writers, analysts, and AI-assisted workflow users who need a clean handoff artifact instead of a loose idea or full spec.
The real job-to-be-done is clarity: define the user, the action, the value, and the testable outcome in a format engineering and QA can use. Compared with a generic prompt, the user-story skill gives you a repeatable structure and a tighter scope, which matters when you want fewer ambiguous stories and fewer review cycles.
Best fit for product-to-engineering handoff
Use this user-story skill when you already know the intent but need to express it in a way that is concise, testable, and easy to estimate. It is especially useful for turning PRD notes, stakeholder requests, and roadmap bullets into a story that supports implementation.
What makes user-story different
The key differentiator is the combination of a standard user-story format with explicit acceptance criteria. That means the output is not just readable; it is also easier to validate, split, and discuss. The user-story skill is more useful than a freeform prompt when you need consistent story quality across multiple items.
When it is the right tool
Choose user-story for feature work, workflow changes, onboarding steps, and other scoped outcomes where one user action leads to one measurable result. It is a strong fit for Technical Writing teams that support product documentation, because it keeps product intent and success criteria aligned.
How to Use user-story skill
Install the user-story skill
Install with:
npx skills add deanpeters/Product-Manager-Skills --skill user-story
After install, start by reading skills/user-story/SKILL.md, then check template.md and examples/sample.md to see the intended structure and quality bar. If you plan to automate story generation, also inspect scripts/user-story-template.py so you know which fields the skill expects.
Give it the right input
The user-story skill works best when you provide a concrete user, a single desired action, and the business or user value behind it. Strong inputs look like this:
- Persona:
trial user,support agent,account owner - Action:
reset my password,export invoices,approve a request - Outcome:
so that I can regain access quickly
Weak inputs like “improve onboarding” usually produce vague output because they do not identify who, what, or why.
Use a prompt that matches the template
For best user-story usage, ask for one story at a time and include the fields the skill is designed to fill. A good prompt is:
“Write a user-story for a trial user who wants to connect their Google account so that they can sign in faster. Include one summary, the use case, and one scenario with one Given/When/Then set.”
This works better than asking for “a user story about login” because it supplies scope and outcome, which improves acceptance criteria quality.
Read the repo files in this order
For practical user-story guide work, review:
SKILL.mdfor the writing rules and conceptual frametemplate.mdfor the exact Markdown shapeexamples/sample.mdfor good vs. bad story qualityscripts/user-story-template.pyif you want repeatable generation
That order helps you see both the format and the guardrails before you draft your own story.
user-story skill FAQ
Is user-story only for product managers?
No. The user-story skill is also useful for technical writers, analysts, designers, and engineers who need a shared artifact for planning or implementation. Anyone who has to translate intent into a testable story can use it.
How is user-story different from a normal prompt?
A normal prompt may produce a story-shaped paragraph, but the user-story skill pushes for a consistent structure: summary, persona, action, outcome, scenario, and acceptance criteria. That consistency matters when stories need to be reviewed, estimated, or split.
Is user-story beginner friendly?
Yes, if you can describe a user, a goal, and a desired result. The main beginner mistake is starting with the solution instead of the user problem. If you can answer “who needs this and why,” the skill is a good fit.
When should I not use user-story?
Do not use user-story for broad strategy documents, multi-step epics, architecture decisions, or feature specs with many interdependent outcomes. If you need multiple behaviors, the story is probably too large and should be split before implementation.
How to Improve user-story skill
Give better source material
The biggest quality gain comes from sharper inputs. Include the exact persona, the trigger, the desired outcome, and any constraint that affects the story, such as platform, role, or permission level. For example, “billing admin on desktop exports invoice history” is much better than “user downloads data.”
Watch for scope creep
A common failure mode in user-story output is trying to fit several outcomes into one story. If your draft needs multiple When/Then paths, separate user actions, or mixed user types, split it first. The repo’s template and examples suggest one main behavior per story for a reason.
Improve the acceptance criteria
If the first draft feels soft, add more concrete context for the Given state and more precise success conditions for the Then. Strong acceptance criteria describe what a reviewer can observe, not just what the system should “support.” This is especially important when using user-story for Technical Writing, where ambiguity makes downstream docs harder to write.
Iterate from review comments
Use the first output as a draft, then refine by correcting the persona, tightening the outcome, and removing any acceptance criteria that are implementation guesses. If reviewers ask “who is this for?” or “how do we test it?”, feed those questions back into the next prompt so the user-story skill can produce a more usable revision.