# Gherkin Spec Writer

> Generate structured, BDD-compliant Gherkin .feature files from requirements, user stories, or feature descriptions. Use this skill whenever the user wants to write Gherkin scenarios, create .feature files, or convert requirements into BDD format. Triggers on: "write Gherkin", "generate .feature file", "create BDD scenarios", "Given When Then", "Scenario Outline", "convert this to Gherkin", "write acceptance tests in Gherkin", "BDD spec", "Cucumber feature file". Always use this skill for any Gherkin or BDD specification work.

- Skill: `oumaimah-qa/gherkin-spec-writer` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add oumaimah-qa/gherkin-spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oumaimah-qa/gherkin-spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oumaimah-QA (https://skillmd.com/u/oumaimah-qa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oumaimah-qa/gherkin-spec-writer

---


# Gherkin Spec Writer

## Purpose

Generate clean, structured, executable Gherkin `.feature` files from any requirement.
Ready to use with Cucumber, Behave, Karate, or any BDD framework.

---

## Input Accepted

- User Story (As a / I want / So that)
- Acceptance criteria (bullet points or draft Given/When/Then)
- Plain feature description in natural language
- Existing test cases to convert to Gherkin format
- API endpoint or UI flow description

---

## Generation Process

### Step 1 — Extract Scenarios

Identify each distinct test scenario:
- Minimum: 1 happy path
- 1 negative per business rule
- 1 boundary scenario per numeric or date field
- 1 security/auth scenario if authentication is involved

### Step 2 — Identify Shared Context

Extract repeated `Given` steps shared by all scenarios → move to `Background`.
If a precondition applies only to some scenarios, keep it inside those scenarios.

### Step 3 — Group Data-Driven Cases

Identify 3+ similar scenarios that differ only by input values → use `Scenario Outline + Examples`.

### Step 4 — Apply Tags

Tag each scenario using the convention in `references/gherkin-tags.md`.

---

## Gherkin Structure

```gherkin
Feature: [Short feature name — noun phrase]
  As a [role]
  I want [action]
  So that [benefit]

  Background:
    Given [shared precondition — max 3 steps]
    And   [shared precondition]

  @smoke @critical
  Scenario: [Descriptive title — what is being tested]
    Given [initial state — system or user context]
    When  [single action performed by the actor]
    Then  [observable, verifiable outcome]
    And   [additional outcome if needed]

  @negative @high
  Scenario: [Negative case title]
    Given [context]
    When  [invalid action or bad condition]
    Then  [error or rejection outcome]

  @boundary @regression
  Scenario Outline: [Title with <variable>]
    Given [context with <variable>]
    When  [action with <variable>]
    Then  [result is <expected>]

    Examples:
      | variable | expected |
      | value1   | result1  |
      | value2   | result2  |
      | value3   | result3  |
```

---

## Step Writing Rules

| Step | Rule | Example |
|---|---|---|
| Given | Describes state, not action | `Given the user has a balance of 1000 USD` |
| When | One single action | `When the user submits the transfer form` |
| Then | Observable outcome only | `Then the confirmation message is displayed` |
| And | Continuation of previous step type | `And the user balance is updated` |
| But | Excluded or negative continuation | `But the original transaction is not modified` |

**Never:**
- Put technical/database details in `Then`
- Combine multiple actions in one `When`
- Write `Then the system saves the record` → write `Then the transaction is visible in the history`

---

## Output Format

Generate a complete `.feature` file including:
1. Feature header with role/goal description
2. Background (if shared preconditions exist)
3. All scenarios, tagged and ordered: Happy Path → Negative → Boundary → Security → Edge
4. Scenario Outlines with complete Examples tables

Always end with a comment block:
```gherkin
# Generated by QIOS gherkin-spec-writer
# Total scenarios: [N]
# Tags: @smoke [N]  @regression [N]  @critical [N]  @negative [N]
```

---

## References

- `references/gherkin-best-practices.md` — Complete style guide and rules
- `references/gherkin-tags.md` — Full tagging strategy and conventions
- `../../_shared/gherkin-style-guide.md` — Shared source of truth
- `examples/input-requirement.md` — Example input
- `examples/output-transfer.feature` — Complete real-world example
- `examples/output-login.feature` — Second complete example