gherkin-authoring

Skill: gherkin-authoring

Policy Capsule

• Write Given clauses as stative preconditions, When as a single business action, and Then as a user-visible outcome.
• Allow exactly one When per scenario; if you need two, split into two scenarios.
• Never assert on HTTP status codes, SQL state, DOM selectors, URLs, or JSON payloads inside .feature prose — push those to contract tests.
• Tag every Scenario or Outline with exactly one canonical @domain-* tag and the appropriate risk/platform tags from the gherkin-standards taxonomy.
• Use Background only when every scenario in the file genuinely shares the precondition with no per-scenario variation.
• Complete the step-reuse sequence in gherkin-standards.md § Step Reuse before authoring any scenario text; that rule is the only home for it.
• Author one scenario per PRD acceptance criterion; for bounded matrices, use a Scenario Outline with ≤12 Examples rows.
• Use third-person present-tense, role-qualified actors (the billing-admin), never first person.

The enforcement rules — tag taxonomy, forbidden patterns, Outline conventions, selector discipline, step reuse — live in .agents/rules/gherkin-standards.md, which is the SSOT. This skill shows authors how to apply those rules; read the rule for the what.

Long-form reference — read on demand

The step-definition library layout and the pre-PR authoring checklist live in the on-demand sibling reference.md. Open a section only when the task engages it.

• Step-Definition Library Structure
• Authoring Checklist

Cross-References

• SSOT rules: .agents/rules/gherkin-standards.md.
• Runtime wiring: playwright-bdd.
• Browser-level conventions: playwright.
• Test-layer scope: testing-standards.md.
• Example feature: examples/invoice-issue.feature.