using-user-stories_skill

Overview

This skill documents and tracks feature implementation using user stories. It provides a clear workflow for authoring stories, building features, and marking acceptance criteria as passing so teams and agents can verify work and maintain a historical record.

How this skill works

You author or update user stories that list verifiable, imperative steps and a passes flag. Developers or AI agents implement the feature, run tests or manual checks, then set passes: true when all steps pass. A verification script validates story format, required fields, and step integrity across the collection.

When to use it

• Starting a new feature or user flow to define acceptance criteria
• Fixing a bug that requires testable validation steps
• Translating a design or spec into implementable tasks
• Breaking a large feature into smaller, testable increments
• Coordinating work between humans and automated agents

Best practices

• Write steps as short imperative commands (e.g., 'Navigate to /settings')
• Make each step verifiable with URLs, button names, or expected values
• Keep steps specific and atomic so tests or manual checks are reliable
• Update passes to true only after manual or automated verification
• Commit the implemented code and the updated story together

Example use cases

• Define acceptance steps for a new chat deletion feature and mark passing after end-to-end tests
• Create stories for regression fixes so QA can reproduce and verify fixes
• Break a checkout flow into multiple stories for incremental implementation
• Have AI agents scan for stories with passes: false and implement missing steps
• Run the verification script before CI to ensure story files are valid