story — Claude Code skill: what it does, how to install
story is a Claude Code skill that refines a single user story before development, drafting acceptance criteria and a concise implementation plan.
MIT ★ 265 updated 2026-11-11
npx skills add nschurmann/hola-ai --skill story -a claude-codeWhat story does
The skill evaluates the provided story alongside the existing codebase and agent instructions. It generates acceptance criteria in Given/When/Then format strictly from the user perspective, avoiding implementation details. When a story demands more than three criteria, the agent recommends splitting it into smaller items and proceeds with the first one.
Along with criteria, it prepares an implementation outline capped at five bullet points without mentioning code or file paths. Architectural ideas go into an optional suggestions section only when existing code directly calls for them. The final output is a markdown block ready for an issue tracker, awaiting manual sign-off.
What it helps with
- write acceptance criteria in Given/When/Then format
- split an oversized user story into smaller tasks
- build a high-level implementation plan without code details
- define what stays out of scope for the current story
Example prompts for the agent
- Refine this story: As a user, I want to reset my password via an email link
- Generate acceptance criteria and a mini plan for the order filter ticket
How to install story
1Skills CLI (Vercel)
npx skills add nschurmann/hola-ai --skill story -a claude-code2Manually: put the files in place
~/.claude/skills/story/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/story/
1Skills CLI (Vercel)
npx skills add nschurmann/hola-ai --skill story -a codex2Manually: put the files in place
.agents/skills/story/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nschurmann/hola-ai --skill story -a cursor2Manually: put the files in place
.cursor/skills/story/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nschurmann/hola-ai skills/story2Manually: put the files in place
.github/skills/story/SKILL.md1Skills CLI (Vercel)
npx skills add nschurmann/hola-ai --skill story -a gemini-cli2Platform CLI
gemini skills install https://github.com/nschurmann/hola-ai --path skills/storyManually: put the files in place
.devin/skills/story/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about story
How to install story in Claude Code?
Run npx skills add nschurmann/hola-ai --skill story -a claude-code. You can also save the file directly to ~/.claude/skills/story/SKILL.md.
What does story do?
It reviews a single backlog item against project context, drafts Given/When/Then criteria, and provides a short plan capped at five points.
What happens if a story requires more than three criteria?
The skill suggests splitting it into separate stories using the standard template and continues refining only the first item.
Source text
SKILL.md · MIT
--- name: story description: Takes ONE user story from the backlog, adds acceptance criteria and proposes an implementation plan. disable-model-invocation: true --- # Story We refine a single story, right before building it. You propose and I decide. ## Steps 1. **Read the story** I give you and review the current code and the project's agent instructions file to understand the context. 2. **Acceptance criteria.** Propose in Given/When/Then format. They only describe *what* the user sees or gets, never *how* it's implemented. 3. **If it needs more than 3 criteria, evaluate splitting it.** Deliver the new stories in backlog format (`As a…, I want…, so that…`) for me to add to the tracker, and we continue with the first one. 4. **Mini plan.** 5 bullets max, no code or file names. How it cuts through the layers. 5. **Wait for my approval.** We adjust until I say yes. ## Rules - **Don't invent requirements.** If information is missing, ask me. - **The simplest thing that meets the criteria.** No abstractions, layers, configuration or patterns "for the future". - **Suggest, don't decide.** If a pattern could help, mention it under "Suggestions" with its why. Only suggest it if there's a concrete signal in the current code, not in advance. ## Output format A block ready to paste into the issue. ```markdown ## Story As a <actor>, I want <action>, so that <benefit>. ## Acceptance criteria - [ ] Given <context>, when <action>, then <result>. - [ ] ... ## Plan - ... ## Out of scope - <what's left out of this story, so it doesn't sneak in> ## Suggestions (your call) - <optional> ```
© nschurmann · MIT · nschurmann/hola-ai