Menu
Guide writing well-formed user stories with acceptance criteria following best practices
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Generate Mermaid architecture diagrams showing system components, layers, and data flows
Proactively identify at-risk issues and PRs: stale items, blocked work, deadline risks, scope creep, and unassigned high-priority items
Extract common questions from closed GitHub issues and generate an FAQ document with answers
Search project notes by topic, synthesize findings into a consolidated summary with cross-references
Proactively identify information gaps in project context and generate actionable questions to surface missing requirements, unclear specifications, or documentation gaps
Generate Mermaid dependency graphs showing issue relationships, blocking chains, and critical paths
| name | user-story-template |
| description | Guide writing well-formed user stories with acceptance criteria following best practices |
| instructions | When creating new features, writing GitHub issues for product work, or documenting user requirements |
| tags | ["user-story","requirements","agile","planning"] |
| allowed_tools | ["github","notes"] |
This skill helps create well-formed user stories that follow product management best practices.
Activate this skill when:
Every user story should follow this structure:
Clear, concise feature name (what, not how)
As a [type of user]
I want [an action or feature]
So that [benefit or value]
Examples:
Clear, testable conditions that must be met. Use "Given-When-Then" format:
Given [initial context]
When [action occurs]
Then [expected outcome]
Example:
Given I am viewing the project dashboard
When I click the "Filter" button
Then I see a dropdown with all available labels
And I can select multiple labels to filter by
And the issue list updates to show only matching issues
Dependencies:
Open Questions:
Technical Notes:
Design Assets:
Before finalizing a user story, verify:
❌ "Add a REST endpoint at /api/v2/users with authentication" ✅ "As an admin, I want to manage user accounts via API, so that I can automate user provisioning"
❌ "Make the dashboard better" ✅ "As a manager, I want to see project velocity trends, so that I can forecast delivery dates"
❌ "As a user, I want dark mode" ✅ "As a user, I want dark mode, so that I can reduce eye strain during evening work sessions"
Stories without clear acceptance criteria lead to:
When creating user stories:
Title: Multi-Project Dashboard View
User Story: As a product manager overseeing multiple projects I want to view aggregated metrics across all my projects in one dashboard So that I can identify bottlenecks and allocate resources effectively
Acceptance Criteria:
Given I manage 3 active projects When I navigate to the "Overview" dashboard Then I see a summary card for each project showing:
And I can click any project card to drill into details And the dashboard loads in under 2 seconds And data refreshes every 5 minutes automatically
Dependencies:
Open Questions:
Technical Notes:
Design Assets: