Skip to main content
skill CX Codex

user-stories · daveebbelaar — Claude Code skill: backlog and installation

A skill for Claude Code that turns app briefs, research, or screen indexes into prioritized user stories with checkable acceptance criteria. It runs after app-brief or clone, or when asked to plan features and choose what to build first.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill user-stories -a claude-code
Open on GitHub

What user-stories does

The skill reads docs/BRIEF.md, research files under docs/research/*.md, and docs/screens/INDEX.md when those files exist, then writes docs/STORIES.md. Each story covers one user action and can link screenshots, dependencies, and a status. Acceptance criteria carry a check method: snapshot, unit test, self-test, or manual review.

The backlog is split into milestones, from the app’s core loop through system features and polish. M1 contains 5 to 10 stories; when the total exceeds 60, move stories to ## Later. For M1 stories that add UI, the ux-design skill tool adds a UX: block and starts docs/GLOSSARY.md.

What it helps with

  • turn an app brief into separate user actions
  • give stories acceptance criteria with a defined check method
  • connect stories to screenshots and dependencies
  • prioritize features into development milestones
  • record features left out of the first version

Example prompts for the agent

  • Create user stories from docs/BRIEF.md and save them to docs/STORIES.md.
  • Turn the app features into a prioritized backlog with checkable acceptance criteria.
  • Use the research and screen index in docs/ to decide what to build first.

How to install user-stories

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill user-stories -a claude-code

2Manually: put the files in place

~/.claude/skills/user-stories/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/user-stories/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about user-stories

How do I install user-stories in Claude Code?

Run npx skills add daveebbelaar/bama --skill user-stories -a claude-code. The skill file is placed at ~/.claude/skills/user-stories/SKILL.md.

What does user-stories do?

It creates docs/STORIES.md with prioritized user stories and checkable acceptance criteria based on an app brief, research, or a screen index.

How are acceptance criteria checked?

Each criterion is labeled for a snapshot, unit test, self-test, or manual review. A story describes one user action.

Source text

SKILL.md · MIT
---
name: user-stories
description: Prioritized backlog of user stories with checkable acceptance criteria (docs/STORIES.md) for a macOS app, built from a brief, research, or screen index. Use after app-brief or clone, or when the user asks for user stories, a backlog, a feature list, or "what do we build first".
---

# User stories

Screens show what an app looks like. Stories say what a person does with
it. You build and test stories, not screens.

Read `docs/BRIEF.md`, `docs/research/*.md`, and `docs/screens/INDEX.md`
where they exist. Write `docs/STORIES.md`.

## Story format

```markdown
### S-012 Complete a task with the keyboard
As the user, I select a task and press Command-Return to complete it.
Screens: 01-inbox.png, 02-today.png
Depends: S-004
Acceptance:
- [snap] The circle fills and the row fades out within half a second.
- [self] An "Undo" banner shows for five seconds; Command-Z also undoes it.
- [unit] A recurring task moves to its next date.
Status: todo
```

- One action per story. "Rename a project from its context menu", not
  "Manage projects".
- Every acceptance line starts with how it is checked: `[snap]` snapshot,
  `[unit]` unit test, `[self]` self-test, `[manual]` a person must try it.
  "Works well" is not checkable.
- `Screens:` links reference screenshots, so `improve-loop` knows what to
  compare. Without a reference app, name the snapshot pages that will show
  the story. A panel, sheet, or menu needs its own snapshot page.
- `Depends:` (optional) lists stories that must be done first.
- Keep a control and the only surface that shows it in one story: a
  highlighting field that lives only in the quick-add panel ships with the
  panel.
- Status: `todo`, `doing`, `done`, or `dropped`.

## Milestones

Each milestone ends with an app the user can use for a day.

1. **M1 Core loop**: the one thing the app is for, end to end. Data
   survives a restart.
2. **M2 Organize**: the main structure, sidebar pages, moving items.
3. **M3 Time**: dates, Today and Upcoming, recurrence, reminders.
4. **M4 Speed**: quick-add panel, global shortcut, natural language input,
   keyboard navigation, search, menu commands.
5. **M5 System**: menu bar, Share menu, Shortcuts, notifications, CLI.
6. **M6 Polish**: drag and drop, context menus, empty states, icon, settings.

Rename milestones to fit the app. Inside a milestone, stories that others
depend on come first.

## Seed data

Every attribute the seed data sets (symbols, colors, notes) is something a
story lets the user create in the app. Otherwise snapshots show features
no one can use.

## Leave things out

Drop what exists only for other people or for the vendor: accounts,
sharing, teams, integrations, upgrade prompts, gamification. List them
under `## Dropped`, one line each, so the decision is visible.

## UX notes

For each M1 story that adds a screen, an action, or words, call the Skill
tool with `ux-design`. It adds a `UX:` block under the acceptance lines and
starts `docs/GLOSSARY.md`, so every story uses the same names. Later
milestones get their UX notes in `improve-loop`, just before they are built.

## Size check

M1 has 5 to 10 stories. Over 60 stories in total means version one is too
big: move stories to `## Later`.

Done when every main job in the brief, every "Version one: yes" row in the
research matrix, and every screen in the index maps to a story or a
`Dropped` line, and every M1 story with UI has a `UX:` block.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Notes, tasks and projects →

user-stories by other authors comes first.

user-stories phuryn A skill for Claude Code, Codex, Cursor and other agent CLIs that turns a feature into user stories built on the 3 C's and INVEST. Reach for it when a feature needs to become backlog items. CX Codex +1 3,500installs write-stories Paweł Huryn write-stories is a Claude Code command that turns a feature brief or PRD into backlog items with acceptance criteria. Choose user stories, job stories, or WWA. CX Codex +1 ★ 28,211repo stars deliver-user-stories product-on-purpose deliver-user-stories turns a PRD or feature description into user stories in persona-action-benefit form, with Given/When/Then acceptance criteria and an INVEST check. CX Codex +1 1,000installs user-story-writing aj-geddes user-story-writing structures product requirements into user stories with Given-When-Then acceptance criteria. Helps during sprint planning and backlog refinement. CX Codex +1 798installs bmad-epics-and-stories aj-geddes bmad-epics-and-stories is a Claude Code skill that turns PRDs and architecture into epics and self-contained stories for development handoff. CX Codex +1 138installs writing-user-stories nicepkg writing-user-stories — a skill that teaches agents to write user stories in standard format: persona, action, and benefit. Triggers when you need to define requirements from the user's perspective. CX Codex +1 1installs 02-user-stories AI-Driven Dev 02-user-stories turns an epic, product brief or PRD into ordered user stories with acceptance criteria, then checks whether they are ready to build. CX Codex +1 ★ 571repo stars

From the same set21

The whole set →
app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs layout-grid layout-grid is a Claude Code skill that enforces grid and alignment rules in macOS SwiftUI apps. It runs when building custom UI components or after layout changes. CX Codex +1 1,000installs swift-swiftui The swift-swiftui Claude Code skill sets Swift 6 and SwiftUI practices for macOS apps. It activates while writing, reviewing, or debugging Swift code, including concurrency and Sendable errors. CX Codex +1 1,000installs design-kit design-kit — a skill for Claude Code and Cursor builds a custom macOS SwiftUI design system with tokens and components. Runs when you need a brand look or custom controls. CX Codex +1 1,000installs design-system The design-system Claude Code skill organizes a macOS app’s accent color and design tokens. It activates for requests about themes, shared screen styles, or a style guide. CX Codex +1 1,000installs new-mac-app new-mac-app is a Claude Code skill that scaffolds a native SwiftUI macOS app from a working template. It starts when a new Mac app or project skeleton is requested. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open