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
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/bdd-scenarios/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bdd-scenarios/
1Skills CLI (Vercel)
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a codex2Manually: put the files in place
.agents/skills/bdd-scenarios/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a cursor2Manually: put the files in place
.cursor/skills/bdd-scenarios/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TheBushidoCollective/han plugins/patterns/bdd/skills/bdd-scenarios2Manually: put the files in place
.github/skills/bdd-scenarios/SKILL.md1Skills CLI (Vercel)
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a gemini-cli2Platform CLI
gemini skills install https://github.com/TheBushidoCollective/han --path plugins/patterns/bdd/skills/bdd-scenariosManually: put the files in place
.devin/skills/bdd-scenarios/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TheBushidoCollective/han --skill bdd-scenarios -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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