user-story-skills

user-story-skills

Claude Code skills and slash commands for user story refinement across the full lifecycle — from discovery through post-release.

Each analysis is available as:

• A skill (.claude/skills/story-<name>/SKILL.md) — Claude auto-selects it based on intent, e.g. "review this story for INVEST"
• A slash command (.claude/commands/story-<name>.md) — explicit invocation, e.g. /story-invest <story text>

Install

As a Claude Code plugin (recommended)

This repository is a Claude Code plugin. It is listed in jdinkla-marketplace — inside Claude Code:

/plugin marketplace add jdinkla/claude-marketplace
/plugin install user-story-skills@jdinkla-marketplace

After install, all 27 skills auto-trigger by intent and all 27 /story-* slash commands are available.

Maintainers of other marketplaces: add an entry like the following to your marketplace.json plugins array to list this plugin:

{
  "name": "user-story-skills",
  "source": { "source": "github", "repo": "jdinkla/user-story-skills" },
  "description": "27 skills and slash commands for user story refinement."
}

The version field is intentionally omitted — plugin.json already pins it, and setting it in both places silently lets plugin.json win.

Manual install (no plugin system)

If you prefer to drop the files directly into a project:

git clone https://github.com/jdinkla/user-story-skills.git /tmp/uss
mkdir -p .claude/skills .claude/commands
cp -r /tmp/uss/skills/* .claude/skills/
cp /tmp/uss/commands/*.md .claude/commands/

For a single skill:

cp -r /tmp/uss/skills/story-invest .claude/skills/
cp /tmp/uss/commands/story-invest.md .claude/commands/

For global install across all projects, copy into ~/.claude/skills/ and ~/.claude/commands/ instead.

Usage

Once installed, either describe what you want and let Claude pick the skill…

review this user story against INVEST criteria <story text>

…or call the slash command directly:

/story-invest /story-gherkin @stories/login.md /story-edge-cases

Every skill accepts the story via:

1. Text passed as args to the skill / slash command
2. A file path (@path/to/story.md)
3. The current selection or most recently referenced story in the conversation
4. If none of the above — Claude will ask you to paste or point to a story

Catalog

All 27 analyses, grouped by lifecycle stage:

Discovery — Why are we doing this?

Skill	Purpose
story-persona-empathy	Simulate 2–4 user personas and critique whether the story actually solves their pain points
story-user-journey	Map the story to 1–3 broader user journeys and surface gaps, dead ends, broken handoffs

Refine — What exactly are we doing?

Skill	Purpose
story-invest	Score against INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) with coaching notes
story-kickoff	Development-readiness checklist across Clarity, Scope, Dependencies, Design, Technical, Team
story-questions	Surface unknowns, assumptions, and clarifying questions by category and priority
story-business-value	Articulate user, business, strategic, and technical value + success metrics
story-summary	30-second quick-reference synopsis for handoff, docs, or backlog scanning
story-alternative-solutions	Propose 2–4 alternative technical/UX approaches with tradeoff analysis
story-stakeholder-impact	Identify downstream teams, communication plan, and timing
story-requirements-breakdown	Split into 3–7 independently deliverable sub-stories with dependencies
story-nonfunctional	Extract 6–12 measurable NFRs (performance, scalability, security, reliability, a11y, …)
story-gherkin	Translate to 2–5 BDD scenarios in Given/When/Then form

Plan — How are we doing it?

Skill	Purpose
story-implementation	6–12 technical tasks broken down by phase, with effort estimates and risks
story-agentic-ai	Score suitability for autonomous AI-agent implementation across 8 criteria
story-auto-documentation	Pre-draft Confluence / Notion / README / API doc updates
story-synthetic-data	Specify test data entities, scenarios, constraints, and seed SQL

QA — Did we do it right?