write-spec

Write Gherkin feature specifications into .feature files for BDD workflows.

Updated Jun 3, 2026
One-click install
npx skills add https://github.com/0xdeafcafe/skills --skill write-spec-0xdeafcafe
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: write-spec
Source: https://github.com/0xdeafcafe/skills/tree/main/skills/write-spec
Command: npx skills add https://github.com/0xdeafcafe/skills --skill write-spec-0xdeafcafe

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you create clear, testable Gherkin feature specifications without guessing the repository's conventions or missing important scenarios. It reduces the risk of vague, incomplete, or misleading specs by guiding you through the right questions before writing the .feature file.

Core Features & Use Cases

  • Repository-aware spec writing: Finds the existing specs location, naming style, tagging patterns, and phrasing conventions so new feature files fit the codebase.
  • Interactive scenario discovery: Draws out the golden path, edge cases, error paths, and scope boundaries through conversation instead of jumping straight to a weak draft.
  • Context linking: Looks for related ADRs or PR context and connects the spec to prior design decisions when relevant.
  • Validation-oriented workflow: Encourages review, writes the final .feature file, and verifies Gherkin syntax with a dry run when a BDD runner is available.
  • Use case: When a team wants to document a new or existing feature in Cucumber, Behave, SpecFlow, or pytest-bdd style, this Skill helps produce a concrete, maintainable spec that matches local practice.

Quick Start

Ask the write-spec skill to draft a Gherkin feature file for the behavior you want to capture and be ready to answer a few questions about the main flow, edge cases, and expected outcomes.

Frequently Asked Questions about write-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write Gherkin feature files from loosely defined feature requests?

Writing Gherkin feature specifications involves interactively extracting the golden path and edge cases from loose requests, then generating a concrete .feature file that matches your repository's existing naming and phrasing conventions.

What is the best way to ensure new BDD specs match existing repository conventions?

The best way to match repository conventions is to use a spec-writing process that discovers existing spec folders, ADR context, and tagging patterns, ensuring new Gherkin feature files align with local Cucumber or Behave practices.

Does this approach work with pytest-bdd and SpecFlow workflows?

Yes, this Gherkin spec-writing approach works with pytest-bdd, SpecFlow, Behave, and Cucumber workflows, applying consistent BDD scenario discovery and optional dry-run syntax verification across these BDD runners.

How do I discover edge cases and error paths when writing behavior-driven development specs?

You discover edge cases and error paths in BDD specs through an interactive scenario discovery process that asks targeted questions to draw out scope boundaries and expected outcomes before drafting the final Gherkin file.

Can I validate Gherkin syntax with a dry run before saving the feature file?

Yes, you can validate Gherkin syntax with a dry run when a BDD runner is available, verifying the generated .feature file syntax after writing the behavior specifications and encouraging a final review.

When should I link architecture decision records to a new feature spec?

You should link ADRs to a new feature spec when prior design decisions impact the current behavior, allowing the spec-writing process to look up related ADR context and connect the Gherkin scenarios to relevant architectural choices.