Skip to main content
skill CX Codex

bdd-patterns — Claude Code skill: what it does, how to install

bdd-patterns helps agents write BDD specifications with Given–When–Then, feature files, and acceptance criteria. Use it when behavior must guide implementation.

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

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

What bdd-patterns does

bdd-patterns gives BDD work a clear shape: Given describes the starting context, When names the event, and Then states the expected result. It covers feature-file layout, shared Background steps, data-driven Scenario Outlines, Examples tables, and Cucumber step definitions.

The skill is useful for acceptance tests, living documentation, and checking business behavior before implementation. Its guidance favors user-centered scenarios, focused behaviors, and declarative wording instead of UI details.

The metadata allows only Read and Bash, so that restriction matters when a task requires the agent to edit files directly.

What it helps with

  • turn requirements into acceptance criteria
  • structure behavior with Given–When–Then
  • organize a feature file with shared setup
  • build a data-driven Scenario Outline
  • write Cucumber step definitions

Example prompts for the agent

  • Turn these login requirements into BDD scenarios using Given–When–Then.
  • Create a shopping-cart feature file with shared setup and separate add and remove scenarios.
  • Write a password-validation Scenario Outline with an Examples table.

How to install bdd-patterns

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

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

Questions about bdd-patterns

How do I install bdd-patterns in Claude Code?

Run npx skills add TheBushidoCollective/han --skill bdd-patterns -a claude-code, then check ~/.claude/skills/bdd-patterns/SKILL.md.

What does bdd-patterns do?

It guides the agent through BDD specifications, feature files, Given–When–Then scenarios, acceptance criteria, data tables, and Cucumber step definitions.

Can I invoke bdd-patterns as a slash command?

No. The skill metadata sets user-invocable: false, so the agent applies it from the task context rather than through a direct command.

Source text

SKILL.md · Apache-2.0
---
name: bdd-patterns
user-invocable: false
description: Use when applying Behavior-Driven Development patterns including Given-When-Then structure, feature files, and acceptance criteria. Use when writing BDD-style tests and specifications.
allowed-tools:
  - Bash
  - Read
---

# BDD Patterns

Master Behavior-Driven Development patterns to write clear, business-readable specifications that drive implementation.

## Given-When-Then Structure

The fundamental BDD pattern uses three parts:

- **Given**: The initial context or preconditions
- **When**: The action or event being tested
- **Then**: The expected outcome or result

```gherkin
Feature: User Authentication

  Scenario: Successful login with valid credentials
    Given a registered user with email "[email protected]"
    And the user has password "secure123"
    When the user submits the login form with correct credentials
    Then the user should be redirected to the dashboard
    And a session should be created
```

## Feature File Organization

```gherkin
Feature: Shopping Cart
  As a customer
  I want to manage items in my cart
  So that I can purchase products I'm interested in

  Background:
    Given I am logged in as a customer
    And the product catalog is available

  Scenario: Add item to empty cart
    Given my cart is empty
    When I add "Blue T-Shirt" to my cart
    Then my cart should contain 1 item
    And the cart total should be $29.99

  Scenario: Remove item from cart
    Given my cart contains "Blue T-Shirt"
    When I remove "Blue T-Shirt" from my cart
    Then my cart should be empty
```

## Scenario Outlines for Data-Driven Tests

```gherkin
Scenario Outline: Password validation
  Given I am on the registration page
  When I enter password "<password>"
  Then I should see "<message>"

  Examples:
    | password    | message                        |
    | abc         | Password too short             |
    | abcdefgh    | Password needs a number        |
    | abcdefgh1   | Password accepted              |
    | abcdefgh1!  | Password accepted              |
```

## Step Definition Patterns

```ruby
# Ruby/Cucumber example
Given('a registered user with email {string}') do |email|
  @user = User.create!(email: email, password: 'password123')
end

When('the user submits the login form with correct credentials') do
  visit login_path
  fill_in 'Email', with: @user.email
  fill_in 'Password', with: 'password123'
  click_button 'Log In'
end

Then('the user should be redirected to the dashboard') do
  expect(page).to have_current_path(dashboard_path)
end
```

## When to Use This Skill

Use bdd-patterns when you need to:

- Write acceptance tests that stakeholders can understand
- Define behavior before implementation
- Create living documentation from tests
- Bridge communication between developers and business
- Ensure features meet business requirements

## Best Practices

- Write scenarios from the user's perspective
- Keep scenarios focused on single behaviors
- Use declarative language, not implementation details
- Reuse step definitions across scenarios
- Use Background for common setup steps
- Keep feature files organized by domain area

## Common Pitfalls

- Writing scenarios that are too technical
- Coupling steps to specific UI implementations
- Creating overly complex scenario outlines
- Not maintaining feature files as code changes
- Mixing multiple behaviors in one scenario

© TheBushidoCollective · Apache-2.0 · TheBushidoCollective/han

Similar skills

All skills for Testing and QA →

From the same set36

The whole set →
cpp-modern-features The cpp-modern-features skill guides an agent through C++11–20 features, from type deduction and lambdas to structured bindings. Use it while writing or updating modern C++ code. CX Codex +1 246installs 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-scenarios This skill helps turn requirements into BDD scenarios, acceptance criteria, and edge cases. Use it to clarify expected behavior before implementation. CX Codex +1 180installs 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

Project sponsors

Companies that keep this analytics open