Skip to main content
skill CX Codex

bdd-scenarios — Claude Code skill: BDD scenarios and setup

This skill helps turn requirements into BDD scenarios, acceptance criteria, and edge cases. Use it to clarify expected behavior before implementation.

Apache-2.0 180 installs ★ 201 updated 2026-09-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a claude-code
Open on GitHub

What bdd-scenarios does

The skill guides the agent to describe one behavior per scenario in domain language, focusing on outcomes rather than interface clicks or implementation details. It covers acceptance criteria organized around rules, negative cases, and tags for grouping scenarios.

Its suggested workflow starts with the main path, then checks edge cases and applies tags. Keep scenarios short and independent of one another. That structure can expose gaps before implementation; the scenarios are also intended for review with stakeholders.

What it helps with

  • define acceptance criteria for a user story
  • document expected system behavior
  • cover invalid inputs and edge cases
  • group scenarios with tags for filtering

Example prompts for the agent

  • Write BDD scenarios for this user story and include acceptance criteria.
  • Review the registration scenarios and add missing edge cases and negative tests.
  • Organize the login scenarios with tags, separating the main flow from account-lockout behavior.

How to install bdd-scenarios

1Skills CLI (Vercel)

npx skills add TheBushidoCollective/han --skill bdd-scenarios -a claude-code

2Manually: put the files in place

~/.claude/skills/bdd-scenarios/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bdd-scenarios/

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

Questions about bdd-scenarios

How do I install bdd-scenarios in Claude Code?

Run npx skills add TheBushidoCollective/han --skill bdd-scenarios -a claude-code. The skill file is available at ~/.claude/skills/bdd-scenarios/SKILL.md.

What does bdd-scenarios do?

It helps write behavior specifications as BDD scenarios, including acceptance criteria and edge cases.

How does bdd-scenarios help organize scenarios?

Start with the main path, then add edge cases. Tags can group scenarios and make filtering easier.

Source text

SKILL.md · Apache-2.0
---
name: bdd-scenarios
description: Use when writing effective BDD scenarios including acceptance criteria, edge cases, and scenario organization. Use when defining behavior specifications.
allowed-tools:
  - Bash
  - Read
---

# BDD Scenarios

Learn to write clear, maintainable BDD scenarios that effectively capture business requirements and drive implementation.

## Writing Good Scenarios

A good scenario should be:

- **Specific**: Test one behavior
- **Declarative**: Describe what, not how
- **Business-focused**: Use domain language
- **Independent**: No dependencies on other scenarios

```gherkin
# Good scenario - specific and declarative
Scenario: Customer receives loyalty discount
  Given a customer with Gold membership status
  And a cart total of $100
  When the customer proceeds to checkout
  Then a 10% loyalty discount should be applied
  And the final total should be $90

# Bad scenario - too implementation-focused
Scenario: Apply discount
  Given I click the membership dropdown
  And I select "Gold" from the list
  When I click the checkout button
  Then the JavaScript calculates 10% off
```

## Acceptance Criteria Format

```gherkin
Feature: Order Refunds

  # Rule-based acceptance criteria
  Rule: Full refunds are available within 30 days

    Scenario: Refund requested within return window
      Given an order placed 15 days ago
      When the customer requests a refund
      Then a full refund should be processed

    Scenario: Refund requested after return window
      Given an order placed 45 days ago
      When the customer requests a refund
      Then the refund should be denied
      And the customer should see "Return window expired"
```

## Edge Case Scenarios

```gherkin
Feature: User Registration

  Scenario: Successful registration
    Given I am on the registration page
    When I submit valid registration details
    Then my account should be created

  # Edge cases
  Scenario: Registration with existing email
    Given a user exists with email "[email protected]"
    When I try to register with email "[email protected]"
    Then I should see "Email already registered"

  Scenario: Registration with invalid email format
    When I try to register with email "not-an-email"
    Then I should see "Please enter a valid email"

  Scenario: Registration with empty required fields
    When I submit the registration form with empty fields
    Then I should see validation errors for required fields
```

## Scenario Tags and Organization

```gherkin
@authentication @critical
Feature: User Login

  @smoke
  Scenario: Basic login flow
    # ...

  @security
  Scenario: Account lockout after failed attempts
    # ...

  @wip
  Scenario: Two-factor authentication
    # Work in progress
```

## When to Use This Skill

Use bdd-scenarios when you need to:

- Define acceptance criteria for user stories
- Document expected system behavior
- Create comprehensive test coverage
- Identify edge cases early in development
- Communicate requirements clearly

## Best Practices

- Start with the happy path scenario
- Add edge cases systematically
- Use tags for organization and filtering
- Keep scenarios at 3-7 steps
- Write scenarios before implementation
- Review scenarios with stakeholders

## Common Pitfalls

- Writing scenarios after implementation
- Including too many steps per scenario
- Using vague or ambiguous language
- Forgetting negative test cases
- Not organizing with tags effectively

© TheBushidoCollective · Apache-2.0 · TheBushidoCollective/han

Similar skills

All skills for Testing and QA →
058-design-bdd Juan Antonio Breña Moral 058-design-bdd — a skill that takes Java teams through Behavior-Driven Development as collaborative discovery practice. Works with trusted behavior facts, concrete examples, and scenarios in shared domain language. CX Codex +1 135installs qa-planning WellApp-ai qa-planning turns a feature into a QA contract: numbered Gherkin scenarios covering every data source, plus acceptance criteria the plan and verification steps can point back to. CX Codex +1 1installs behavior-driven-development FradSer behavior-driven-development — a BDD skill for feature work, bug fixes, and executable tests. It turns behavior examples into failing tests before implementation. CX Codex +1 151installs gherkin-style-testing-cursorrules-prompt-file PatrickJS gherkin-style-testing-cursorrules-prompt-file — a Cursor rule that turns technical test scripts and manual cases into Gherkin scenarios written in plain business language. CX Codex +1 ★ 41,178repo stars serenity-bdd-skill TestMu AI serenity-bdd-skill is a Claude Code skill that creates Java BDD tests with Serenity and the Screenplay pattern. It activates for requests about Serenity, @Steps, or Serenity reports. CX Codex +1 223installs add-cucumber-tests Decathlon add-cucumber-tests turns a functional specification into Cucumber .feature files, using Tzatziki step definitions as the source of legal steps. Built for Java/Spring projects that already depend on Tzatziki or Cucumber. CX Codex +1 1,100installs

From the same set36

The whole set →
react-native-web-testing react-native-web-testing guides AI coding agents through testing React Native Web apps using Jest and React Native Testing Library. CX Codex +1 236installs tailwind-responsive-design The tailwind-responsive-design skill guides responsive, mobile-first Tailwind CSS layouts with breakpoint variants, container queries, and responsive utilities. CX Codex +1 235installs ansible-roles The ansible-roles skill structures Ansible automation as reusable roles. Use it when an nginx setup needs separate tasks, templates, variables, and security steps. CX Codex +1 234installs bdd-patterns bdd-patterns helps agents write BDD specifications with Given–When–Then, feature files, and acceptance criteria. Use it when behavior must guide implementation. CX Codex +1 211installs playwright-bdd-gherkin-syntax playwright-bdd-gherkin-syntax guides agents in drafting Gherkin feature files, outlines, data tables, and tags for Playwright BDD. CX Codex +1 180installs storybook-component-documentation Generates Storybook component documentation via autodocs, MDX pages and JSDoc comments. Useful when creating or updating UI library docs. CX Codex +1 166installs sop-maintenance sop-maintenance is a Claude Code skill for maintaining, versioning, and deprecating SOPs. It keeps operational procedures current after changes to code or infrastructure. CX Codex +1 159installs cucumber-best-practices cucumber-best-practices teaches coding agents to write declarative Gherkin scenarios and maintain independent Cucumber tests. Clean step definitions without UI selectors. CX Codex +1 154installs

Project sponsors

Companies that keep this analytics open