name: gherkin description: Create and format Gherkin feature files using BDD syntax. Use when creating feature files, scenarios, or writing behavioral specifications. allowed-tools: Read, Write, Edit, Glob, WebFetch

Gherkin Feature File Skill

File Naming Convention

IMPORTANT: All Gherkin feature files MUST follow this naming pattern:

gherkin.feature_N.feature

Where N is a sequential number (1, 2, 3, etc.)

Examples:

• gherkin.feature_1.feature
• gherkin.feature_2.feature
• gherkin.feature_42.feature

When Uncertain About Formatting

If you have questions about Gherkin syntax or formatting:

1. First, check the examples below for common patterns
2. If still unclear, refer to the official documentation at: https://cucumber.io/docs/gherkin/reference

Core Gherkin Structure

Basic Feature Template

@tag
Feature: Feature Name

  Background: (Optional - runs before each scenario)
    Given some common precondition

  Scenario: Scenario Name
    Given a precondition
    When an action occurs
    Then an expected outcome
    And another expected outcome

  Scenario Outline: Scenario with examples
    Given a user with <status>
    When they perform <action>
    Then they should see <result>

    Examples:
      | status | action | result  |
      | admin  | delete | success |
      | user   | delete | denied  |

Using Rules

Feature: Feature Name

  Rule: Business Rule Name

    Example: First scenario under this rule
      Given a precondition
      When an action
      Then an outcome

    Example: Second scenario under this rule
      Given another precondition
      When another action
      Then another outcome

  Rule: Another Business Rule

    Example: Scenario for second rule
      ...

Keywords Reference

• Feature: High-level description of a software feature
• Rule: Represents a business rule to implement (optional)
• Example/Scenario: Concrete example illustrating a business rule
• Scenario Outline: Template scenario with multiple inputs via Examples table
• Background: Steps to run before each scenario in the feature
• Given: Describes the initial context (preconditions)
• When: Describes an event or action
• Then: Describes an expected outcome (postcondition)
• And/But: Additional steps for any of the above
• @tag: Annotations for filtering/organizing (e.g., @failing, @wip, @smoke)

Canonical Examples

Example 1: Simple Game Feature

@failing
Feature: Guess the word

  # The first example has two steps
  Scenario: Maker starts a game
    When the Maker starts a game
    Then the Maker waits for a Breaker to join

  # The second example has three steps
  Scenario: Breaker joins a game
    Given the Maker has started a game with the word "silky"
    When the Breaker joins the Maker's game
    Then the Breaker must guess a word with 5 characters

Example 2: Feature with Rules

# -- FILE: features/gherkin.rule_example.feature
@failing
Feature: Highlander

  Rule: There can be only One

    Example: Only One -- More than one alive
      Given there are 3 ninjas
      And there are more than one ninja alive
      When 2 ninjas meet, they will fight
      Then one ninja dies (but not me)
      And there is one ninja less alive

    Example: Only One -- One alive
      Given there is only 1 ninja alive
      Then they will live forever ;-)

  Rule: There can be Two (in some cases)

    Example: Two -- Dead and Reborn as Phoenix
      ...

Best Practices

1. Use descriptive feature names that clearly state the business capability
2. Write scenarios from the user's perspective, not implementation details
3. Keep scenarios independent - each should be able to run alone
4. Use tags to organize and filter scenarios (@smoke, @wip, @failing, etc.)
5. Comments can be added with # but use sparingly
6. Rules help organize related scenarios under business rules
7. Data tables can be used in steps for structured input
8. Doc strings (triple quotes) can include multi-line text in steps

Common Patterns

Data Tables in Steps

Given the following users exist:
  | name  | email           | role  |
  | Alice | alice@test.com  | admin |
  | Bob   | bob@test.com    | user  |

Doc Strings

Given a blog post with content:
  """
  This is a multi-line
  blog post content
  """

Creating New Feature Files

When asked to create a Gherkin feature:

1. Determine the next number by checking existing gherkin.feature_*.feature files
2. Create the file with the correct naming convention
3. Start with a Feature declaration including appropriate tags
4. Use Rules if organizing multiple related scenarios
5. Write clear, behavior-focused scenarios using Given/When/Then
6. Add comments only where they clarify complex logic
7. Review against examples above to ensure consistent style

Additional Resources

For complex questions about Gherkin syntax, step arguments, or advanced features:

• Official Reference: https://cucumber.io/docs/gherkin/reference
• Gherkin Syntax: https://cucumber.io/docs/gherkin/