gherkin-authoring
Skill185 starsChanged 32 days agoMITView on GitHub
Use when drafting, reviewing, or improving Gherkin, Cucumber scenarios, BDD acceptance criteria, feature examples, Scenario Outlines, Backgrounds, Rules, Doc Strings, Data Tables, tags, or Gherkin embedded in Markdown.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- intent-driven-dev/skillsword for word, first seen Aug 22, 2026
Other versions1 project uses a version of this.
Word for word · 1
- intent-driven-dev/skills★ 9100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- acceptance-test-authoringSkill
- architectural-decision-recordsSkill
- c4-diagramsSkill
- glossarySkill
- grill-meSkill
- openspec-git-disciplineSkill
- spec-as-sourceSkill
- test-driven-developmentSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Write Gherkin as executable examples of business behavior.
- Distinctive: line 22
Keep scenarios concrete and short, usually 3-5 steps.
- Distinctive: line 47
Use the language domain experts use.
- Very specific: line 51
Use And and But to improve flow, not to hide new phases of the scenario.
- Very specific: line 52
Avoid identical step text under different step keywords.
- Distinctive: line 53
Use two-space indentation unless preserving existing style.
- Very specific: line 54
Keep Background short and vivid.
- Very specific: line 55
Use Scenario Outline only when examples share the same behavior and differ by data.
- Distinctive: line 72
When Priya chooses a new password with the reset link Then she can sign in with the new password
- Distinctive: line 78
When Priya tries to choose a new password with the reset link Then she is told the reset link has expired And her password is unchanged
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Gherkin Authoring
Overview
Write Gherkin as executable examples of business behavior. Optimize for domain language, concrete examples, and observable outcomes; keep implementation and UI mechanics inside step definitions.
Scope
Use this for standalone .feature files and Gherkin embedded in Markdown or other prose. When Gherkin is inside a Markdown wrapper, review or rewrite only the Gherkin section unless the user asks for broader document edits. Preserve fences, headings, and surrounding prose. If the input includes Markdown around the Gherkin, return the Markdown wrapper with only the Gherkin block changed.
Workflow
- Identify the Gherkin region: whole
.featurefile, fencedgherkinblock, indented block, quoted acceptance criteria, or inline scenario text. - Preserve the surrounding wrapper unless explicitly asked to change it. For Markdown input, return the heading/prose/fence context, not just the fenced Gherkin block.
- Clarify the behavior as examples: initial state, event, observable outcome.
- Choose the smallest structure that expresses the behavior:
Feature, optionalRule,Background,Scenario/Example, orScenario OutlinewithExamples. - Keep scenarios concrete and short, usually 3-5 steps.
- Review syntax and readability before returning: colons, step keywords, duplicate step text, observable outcomes, and table/doc string formatting.
Quick Reference
| Construct | Use for | Syntax note | |
Feature: | One high-level capability per feature document or block | Requires : | |
Rule: | Group scenarios under one business rule | Requires : | |
Scenario: / Example: | One concrete example | Requires : | |
Background: | Short shared context for following scenarios | Requires :; one per Feature or Rule | |
Scenario Outline: | Same behavior with varied data | Requires Examples: and <parameter> placeholders | |
Examples: | Data rows for an outline | Requires : and a table | |
Given | Known state or precondition | No : | |
When | Event or action | No : | |
Then | Observable outcome | No : | |
And / But | Continue the previous step type | No : | |
* | Bullet-like step list | Use sparingly for list-style setup | |
@tag | Group or filter features/scenarios | Place above the item tagged | |
# | Line comment | Line comments only; no block comments | |
""" | Doc String | Passed as final step argument | |
| ` | ` | Data Table | Passed as final step argument |
Authoring Rules
- Use the language domain experts use. Avoid translating business behavior into UI clicks, HTTP calls, database rows, queues, mocks, or implementation details.
Givenputs the system in a known state. Avoid user interaction inGivensteps.Whendescribes one meaningful event.Thendescribes an outcome visible to a user or external system. Do not assert hidden database state unless that is the actual external contract.- Use
AndandButto improve flow, not to hide new phases of the scenario. - Avoid identical step text under different step keywords; Cucumber ignores
Given/When/Thenwhen matching step definitions. - Use two-space indentation unless preserving existing style.
- Keep
Backgroundshort and vivid. If it grows beyond about four lines, use higher-level steps or split byRule/Feature. - Use
Scenario Outlineonly when examples share the same behavior and differ by data. - Escape
|as\|, newline as\n, and backslash as\\inside Data Table cells.
Example
Markdown wrapper preserved; only the Gherkin block is authored:
## Acceptance Criteria
```gherkin
Feature: Password reset
Rule: Reset links expire after their allowed lifetime
Scenario: Customer resets their password before the link expires
Given Priya has requested a password reset
And the reset link is still valid
When Priya chooses a new password with the reset link
Then she can sign in with the new password
Scenario: Customer uses an expired reset link
Given Priya has requested a password reset
And the reset link has expired
When Priya tries to choose a new password with the reset link
Then she is told the reset link has expired
And her password is unchanged
```Common Mistakes
| Mistake | Fix |
| Complaining about Markdown around a Gherkin block | Preserve the wrapper and work only on the Gherkin section. |
| Returning only a fenced Gherkin block when the input was Markdown | Return the original Markdown wrapper with only the Gherkin content changed. |
Feature Checkout or Scenario: Place order: | Add the missing colon after Feature; remove extra colon from the scenario title. |
Given I click the checkout button | Move interaction to When; describe state in Given. |
Then an order row exists in the database | Prefer an observable result, such as an order confirmation. |
Reusing the same step text for Given and Then | Change the wording so the domain meaning is distinct. |
| Long scripts with many UI actions | Raise the abstraction and keep the scenario to the behavior. |
Large Background sections | Use higher-level context or split scenarios by Rule or Feature. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

