home / skills / yellinzero / aico / user-story-writing
This skill converts requirements into well-structured user stories in the As a [user], I want [goal], So that [benefit] format with Given/When/Then acceptance
npx playbooks add skill yellinzero/aico --skill user-story-writingReview the files below or copy the command above to add this skill to your agents.
---
name: aico-pm-user-story-writing
description: |
Transform requirements into well-structured User Stories using "As a [user], I want [goal], So that [benefit]" format with Given/When/Then acceptance criteria.
Use this skill when:
- User asks to "write user story", "create story", "add story"
- User mentions "user story", "backlog item", "story"
- Running /pm.plan and need to break PRD into implementable stories
- Creating backlog items for development team
- Need to formalize a requirement into standard story format
- Converting feature request into actionable story with acceptance criteria
Output: ALWAYS write story files to docs/reference/pm/stories/{story-name}.md
---
# User Story Writing
## ⚠️ CRITICAL RULES - READ FIRST
**BEFORE doing anything, you MUST:**
1. **CHECK EXISTING FILES**:
- Look in `docs/reference/pm/stories/` directory
- If story file already exists, READ it first and ask user if they want to update it
- DO NOT create duplicate story files
2. **ALWAYS USE THIS SKILL**:
- When user says "write story", "create story", "add story" → USE THIS SKILL
- DO NOT write story files directly without using this skill
- This skill ensures proper format and validation
3. **ALWAYS SAVE TO CORRECT PATH**:
- Path: `docs/reference/pm/stories/{story-name}.md`
- NO exceptions, NO other locations
4. **READ CONTEXT FIRST**:
- Read `docs/reference/pm/constitution.md` for product context
- Read related version file from `docs/reference/pm/versions/` if exists
## Language Configuration
Before generating any content, check `aico.json` in project root for `language` field to determine the output language. If not set, default to English.
## Process
1. **Identify user type**: Who benefits from this feature
2. **Define goal**: What they want to do
3. **Clarify value**: Why it matters to them
4. **Write acceptance criteria**: 3-5 Given/When/Then scenarios
5. **Add metadata**: Priority, complexity, dependencies
6. **Save story**: ALWAYS write to `docs/reference/pm/stories/{story-name}.md`
## Story Template
```markdown
# [STORY-ID] Story Title
> Project: [project-name]
> Created: YYYY-MM-DD
> Last Updated: YYYY-MM-DD
**As a** [user type]
**I want** [goal/action]
**So that** [benefit/value]
### Acceptance Criteria
- [ ] Given [context], when [action], then [expected result]
- [ ] Given [context], when [action], then [expected result]
- [ ] Given [context], when [action], then [expected result]
### Notes
- Priority: P1/P2/P3
- Estimated complexity: S/M/L/XL
- Dependencies: [list any dependencies]
```
## Key Rules
- ALWAYS specify the user type (who benefits)
- MUST focus on user value, not technical solution
- ALWAYS include 3-5 testable acceptance criteria
- Use Given/When/Then format for all criteria
- MUST save to `docs/reference/pm/stories/` directory
## Common Mistakes
- ❌ Vague acceptance criteria → ✅ Specific, testable conditions
- ❌ Solution-focused stories → ✅ Focus on user value
- ❌ Missing user type → ✅ Always specify who benefits
This skill transforms requirements into well-structured User Stories using the "As a [user], I want [goal], So that [benefit]" format and includes Given/When/Then acceptance criteria. It enforces product context checks, existing-file checks, and always saves output to docs/reference/pm/stories/{story-name}.md. Use it to produce testable, prioritized backlog items ready for development.
Before generating a story, the skill checks aico.json for language settings and reads docs/reference/pm/constitution.md plus any relevant version files. It looks in docs/reference/pm/stories/ for an existing file with the same name and prompts for updates rather than creating duplicates. It outputs a markdown file using the required template, with user type, goal, value, 3–5 Given/When/Then acceptance criteria, and metadata (priority, complexity, dependencies).
Where must the story file be saved?
Always save to docs/reference/pm/stories/{story-name}.md. No exceptions.
What if a story file already exists?
Read the existing file first and ask the user whether to update it; do not create a duplicate.
How many acceptance criteria should I include?
Include 3–5 Given/When/Then criteria that are specific and testable.