using-user-stories

Q: How do I install using-user-stories?

Run npx skills add https://github.com/andrelandgraf/fullstackrecipes --skill using-user-stories in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/using-user-stories/ (personal) or .claude/skills/using-user-stories/ (project).

by andrelandgrafProductivity & Automation

Document and track feature implementation with user stories. Workflow for authoring stories, building features, and marking acceptance criteria as passing.

Installs: 106
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/andrelandgraf/fullstackrecipes --skill using-user-stories

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads using-user-stories automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Working with User Stories

Document and track feature implementation with user stories. Workflow for authoring stories, building features, and marking acceptance criteria as passing.

User stories document what features should do and track implementation status. When AI agents work through user stories systematically, they produce better results and leave a clear trail of what was done.

Workflow

When working on features:

Author/Update: Create or modify user story features before building
Build & Test: Implement until tests pass
Mark Passing: Set passes: true when verified

When to Create User Stories

Create user stories when:

Starting a new feature or flow
Fixing a bug that should have test coverage
Implementing requirements from a design or spec
Breaking down a large feature into testable increments

Writing Effective Steps

Steps should be:

Verifiable: Each step can be checked by running the app or tests
Imperative: Written as commands ("Navigate to", "Click", "Verify")
Specific: Include URLs, button names, expected values

Good:

{
  "description": "User deletes a chat",
  "steps": [
    "Navigate to /chats",
    "Click the menu button on a chat",
    "Click 'Delete' option",
    "Confirm deletion in dialog",
    "Verify chat is removed from list"
  ],
  "passes": false
}

Avoid vague steps:

{
  "description": "User deletes a chat",
  "steps": ["Delete a chat", "Check it worked"],
  "passes": false
}

Documenting Work Done

When completing a feature:

Verify all steps work manually or via tests
Update passes: true in the user story
Commit both the implementation and the updated story

This creates a log of completed work that future agents can reference.

Using with AI Agents

AI agents can read user stories to:

Understand what features need to be built
Know the exact acceptance criteria
Find features that still need work (passes: false)
Log their progress by marking features as passing

For automated agent loops, see the Ralph Agent Loop recipe.

Verifying Stories

Run the verification script to check all stories have valid format:

bun run user-stories:verify

This validates:

All files are valid JSON
Each feature has required fields
Steps are non-empty strings
Shows pass/fail counts per file

FAQ

What does the using-user-stories skill do?

Document and track feature implementation with user stories. Workflow for authoring stories, building features, and marking acceptance criteria as passing.

How do I install using-user-stories?

Run npx skills add https://github.com/andrelandgraf/fullstackrecipes --skill using-user-stories in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/using-user-stories/ (personal) or .claude/skills/using-user-stories/ (project).

Which AI agents can use using-user-stories?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is using-user-stories safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains using-user-stories?

It is published by andrelandgraf in andrelandgraf/fullstackrecipes. It has 106 recorded installs.