How do I install the Plan Writing Gherkin Criteria skill?

Run npx skillmds@latest add wahidyankf/plan-writing-gherkin-criteria in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Plan Writing Gherkin Criteria safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Plan Writing Gherkin Criteria?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Plan Writing Gherkin Criteria free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Plan Writing Gherkin Criteria?

wahidyankf (@wahidyankf) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Plan Writing Gherkin Criteria by wahidyankf

Name: Plan Writing Gherkin Criteria
Rating: 4.2 (5 reviews)
Author: wahidyankf

Plan Writing Gherkin Criteria

Guide for writing Gherkin acceptance criteria using Given-When-Then syntax for testable requirements. Covers scenario structure, background blocks, scenario outlines with examples tables, common patterns for authentication/CRUD/validation/error handling, and best practices for clear testable specifications. Essential for writing user stories and plan acceptance criteria

wahidyankf 63c1d38 13 files · 22.9 KB Updated Sep 10, 2026

File contents

Gherkin Acceptance Criteria Skill

Purpose

This Skill provides comprehensive guidance for writing Gherkin acceptance criteria using Given-When-Then syntax to create clear, testable specifications for features and user stories.

When to use this Skill: writing acceptance criteria for user stories, defining testable requirements in plans, specifying expected behaviour for features, and documenting edge cases and error handling.

Core Concepts

What is Gherkin?

Gherkin is a structured language for writing acceptance criteria using Given-When-Then syntax. It enables:

Clear communication: Non-technical stakeholders understand requirements
Testable specifications: Scenarios map directly to automated tests
Complete coverage: All scenarios and edge cases documented
Unambiguous expectations: No room for interpretation

Given-When-Then Structure

Anatomy of a scenario:

Scenario: [Brief description of scenario]
  Given [Initial context/preconditions]
  When [Action or event occurs]
  Then [Expected outcome/postconditions]

Breakdown:

Given: Sets up the context (initial state, preconditions, setup)
When: Describes the action or event (user action, system event, trigger)
Then: Specifies expected outcome (assertions, verification, results)

Journey Coherence

See Journey Coherence for the full rule text, conforming/non-conforming examples, and the canonical convention link.

Basic Scenario Patterns

See Basic Scenario Patterns for three worked patterns: simple success path, error handling, and boundary conditions.

Advanced Gherkin Features

See Advanced Gherkin Features for Background blocks, Scenario Outline with Examples tables, and Data Tables.

Common Domain Patterns

See Domain Patterns — Auth and CRUD and Domain Patterns — Form Validation and API Responses for worked full-feature examples across authentication, CRUD, form validation, and API responses.

Best Practices

See Writing Clear Scenarios and Scenario Independence, UI Coupling, and Style for the DO/DON'T rules, scenario independence, avoiding UI coupling, and declarative vs imperative style — each with good/bad examples.

Common Mistakes

See Common Mistakes for the four most common Gherkin mistakes — too many steps, asserting internal implementation, ambiguous language, and testing multiple behaviours — each with a fix.

Phase Gate Acceptance Checks

See Phase Gate Acceptance Checks for how phase gate checklist items in delivery.md meet the same testability standard as Gherkin scenarios.

Integration with Plans

See Integration with Plans for the plan-level acceptance criteria format and the user story acceptance criteria format.

Reference Documentation

Primary Convention: Acceptance Criteria Convention

Directory Structure Convention: Specs Directory Structure Convention — Where to place feature files in the specs/ directory

Related Conventions: Plans Organization, Maker-Checker-Fixer Pattern

Related Skills: repo-practicing-trunk-based-development, repo-applying-maker-checker-fixer

Related Agents: plan-maker, plan-checker, plan-execution-checker

External Resources: Official Gherkin Reference, Writing Better Gherkin

This Skill packages essential Gherkin acceptance criteria knowledge for writing clear, testable specifications. For additional patterns and examples, consult external Gherkin resources.

---name: plan-writing-gherkin-criteriadescription: Guide for writing Gherkin acceptance criteria using Given-When-Then syntax for testable requirements. Covers scenario structure, background blocks, scenario outlines with examples tables, common patterns for authentication/CRUD/validation/error handling, and best practices for clear testable specifications. Essential for writing user stories and plan acceptance criteria---# Gherkin Acceptance Criteria Skill## PurposeThis Skill provides comprehensive guidance for writing **Gherkin acceptance criteria** using Given-When-Then syntax to create clear, testable specifications for features and user stories.**When to use this Skill:** writing acceptance criteria for user stories, defining testablerequirements in plans, specifying expected behaviour for features, and documenting edge cases anderror handling.## Core Concepts### What is Gherkin?**Gherkin** is a structured language for writing acceptance criteria using Given-When-Then syntax. It enables:- **Clear communication**: Non-technical stakeholders understand requirements- **Testable specifications**: Scenarios map directly to automated tests- **Complete coverage**: All scenarios and edge cases documented- **Unambiguous expectations**: No room for interpretation### Given-When-Then Structure**Anatomy of a scenario**:```gherkinScenario: [Brief description of scenario] Given [Initial context/preconditions] When [Action or event occurs] Then [Expected outcome/postconditions]```**Breakdown**:- **Given**: Sets up the context (initial state, preconditions, setup)- **When**: Describes the action or event (user action, system event, trigger)- **Then**: Specifies expected outcome (assertions, verification, results)## Journey CoherenceSee [Journey Coherence](./reference/step-keyword-cardinality.md) for the fullrule text, conforming/non-conforming examples, and the canonical convention link.## Basic Scenario PatternsSee [Basic Scenario Patterns](./reference/basic-scenario-patterns.md) for three worked patterns:simple success path, error handling, and boundary conditions.## Advanced Gherkin FeaturesSee [Advanced Gherkin Features](./reference/advanced-gherkin-features.md) for Background blocks,Scenario Outline with Examples tables, and Data Tables.## Common Domain PatternsSee [Domain Patterns — Auth and CRUD](./reference/domain-patterns-auth-and-crud.md) and[Domain Patterns — Form Validation and API Responses](./reference/domain-patterns-validation-and-api.md)for worked full-feature examples across authentication, CRUD, form validation, and API responses.## Best PracticesSee [Writing Clear Scenarios](./reference/writing-clear-scenarios.md) and[Scenario Independence, UI Coupling, and Style](./reference/independence-coupling-and-style.md)for the DO/DON'T rules, scenario independence, avoiding UI coupling, and declarative vsimperative style — each with good/bad examples.## Common MistakesSee [Common Mistakes](./reference/common-mistakes.md) for the four most common Gherkin mistakes —too many steps, asserting internal implementation, ambiguous language, and testing multiplebehaviours — each with a fix.## Phase Gate Acceptance ChecksSee [Phase Gate Acceptance Checks](./reference/phase-gate-acceptance-checks.md) for how phasegate checklist items in `delivery.md` meet the same testability standard as Gherkin scenarios.## Integration with PlansSee [Integration with Plans](./reference/integration-with-plans.md) for the plan-level acceptancecriteria format and the user story acceptance criteria format.## Reference Documentation**Primary Convention**: [Acceptance Criteria Convention](../../../repo-governance/development/infra/acceptance-criteria.md)**Directory Structure Convention**: [Specs Directory Structure Convention](../../../repo-governance/conventions/structure/specs-directory-structure.md) — Where to place feature files in the specs/ directory**Related Conventions**: [Plans Organization](../../../repo-governance/conventions/structure/plans.md), [Maker-Checker-Fixer Pattern](../../../repo-governance/development/pattern/maker-checker-fixer.md)**Related Skills**: `repo-practicing-trunk-based-development`, `repo-applying-maker-checker-fixer`**Related Agents**: `plan-maker`, `plan-checker`, `plan-execution-checker`**External Resources**: [Official Gherkin Reference](https://cucumber.io/docs/gherkin/reference/), [Writing Better Gherkin](https://cucumber.io/docs/bdd/better-gherkin/)---This Skill packages essential Gherkin acceptance criteria knowledge for writing clear, testable specifications. For additional patterns and examples, consult external Gherkin resources.

Frequently asked questions