How do I install the Spec Generate skill?

Run npx skillmds@latest add mpiton/spec-generate 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 Spec Generate safe to use?

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

Which AI agents work with Spec Generate?

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 Spec Generate free to use?

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

Who published Spec Generate?

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

Spec Generate by mpiton — Agent Skill

Name: Spec Generate
Author: mpiton

Spec Generate

Generate Gherkin acceptance scenarios from a context.md, with mandatory interview for ambiguities, concrete data, and test-level tags. Use after impact-map, or when the user provides a user story and rules and asks for scenarios.

mpiton 2d77776 3.2 KB Updated Sep 17, 2026

File contents

/spec-generate

Generate Gherkin scenarios from specs/<us-slug>/context.md. The pipeline calls this skill in Phase 2 §3 of the diagram.

When to use

After impact-map produced context.md.
When the user pastes a structured story + rules and asks for acceptance scenarios.

Inputs

specs/<us-slug>/context.md (see impact-map).

Workflow

1. Interview (mandatory before generation)

Read context.md first, and treat it as answered ground. impact-map (or from-issue) already elicited the actor, the action, the goal, and the numbered rules — do NOT re-ask any of that. Re-interviewing fields the user already gave upstream is the main avoidable token cost in the spec phase; thread them forward instead.

Ask only the ambiguities that context.md does NOT already resolve — DO NOT guess on those. For each genuinely-new ambiguity, ask one focused question. Examples of things that always require a question if not already explicit in context.md:

Numeric thresholds without units ("limit of 100" — 100 what?).
Implicit time zones, date formats, currency.
Identity / equality semantics (case sensitivity, trimming).
Default values for omitted fields.
Behavior on the boundary itself (<= vs <).

Stop the interview only when every rule can be expressed with concrete, unambiguous data.

2. Generate scenarios

For each business rule R-NN, produce one .feature file at specs/<us-slug>/<rule-slug>.feature.

Each file MUST contain scenarios covering at least:

Nominal path (tag: @nominal).
Violation of the rule (tag: @violation).
Authorization path if the rule involves access (tag: @auth).
Technical / integration edge if applicable (tag: @technical).
Limits / boundaries for any numeric rule (tag: @limit).

Use concrete data (real values, not placeholders). Example: prefer Given the cart contains 3 items at 19.99 EUR over Given some items in the cart.

Add a # Rule: R-NN comment at the top of each feature file so traceability survives renames.

Triangulation: if a rule is complex, produce multiple examples (Scenario Outline with Examples:) rather than a single example.

3. Test-level tag

Tag each scenario by the appropriate test level:

@use-case — pure domain / use case test.
@e2e — end-to-end with the real adapters.
@ui — UI driver (Playwright, RTL, etc.).

If unsure, ask the user before generating.

Outputs

specs/<us-slug>/<rule-slug>.feature — one per business rule.

Handoff

Next: spec-review on the generated .feature files.

Anti-patterns

Don't generate scenarios for rules that are not in context.md. Push back, ask impact-map to capture them first.
Don't invent assertions; every assertion must trace to a rule.
Don't mock the system under test in the scenario data. Scenarios describe behavior, not implementation.

---name: spec-generatedescription: Generate Gherkin acceptance scenarios from a context.md, with mandatory interview for ambiguities, concrete data, and test-level tags. Use after impact-map, or when the user provides a user story and rules and asks for scenarios.---# /spec-generateGenerate Gherkin scenarios from `specs/<us-slug>/context.md`. The pipeline calls this skill in Phase 2 §3 of the diagram.## When to use- After `impact-map` produced `context.md`.- When the user pastes a structured story + rules and asks for acceptance scenarios.## Inputs- `specs/<us-slug>/context.md` (see [`impact-map`](../impact-map/SKILL.md)).## Workflow### 1. Interview (mandatory before generation)Read `context.md` **first, and treat it as answered ground**. `impact-map` (or `from-issue`) already elicited the actor, the action, the goal, and the numbered rules — do NOT re-ask any of that. Re-interviewing fields the user already gave upstream is the main avoidable token cost in the spec phase; thread them forward instead.Ask only the ambiguities that `context.md` does NOT already resolve — DO NOT guess on those. For each genuinely-new ambiguity, ask one focused question. Examples of things that always require a question if not already explicit in `context.md`:- Numeric thresholds without units (`"limit of 100"` — 100 what?).- Implicit time zones, date formats, currency.- Identity / equality semantics (case sensitivity, trimming).- Default values for omitted fields.- Behavior on the boundary itself (`<=` vs `<`).Stop the interview only when every rule can be expressed with concrete, unambiguous data.### 2. Generate scenariosFor each business rule `R-NN`, produce one `.feature` file at `specs/<us-slug>/<rule-slug>.feature`.Each file MUST contain scenarios covering at least:- **Nominal** path (tag: `@nominal`).- **Violation** of the rule (tag: `@violation`).- **Authorization** path if the rule involves access (tag: `@auth`).- **Technical** / integration edge if applicable (tag: `@technical`).- **Limits / boundaries** for any numeric rule (tag: `@limit`).Use **concrete data** (real values, not placeholders). Example: prefer `Given the cart contains 3 items at 19.99 EUR` over `Given some items in the cart`.Add a `# Rule: R-NN` comment at the top of each feature file so traceability survives renames.Triangulation: if a rule is complex, produce **multiple examples** (Scenario Outline with `Examples:`) rather than a single example.### 3. Test-level tagTag each scenario by the appropriate test level:- `@use-case` — pure domain / use case test.- `@e2e` — end-to-end with the real adapters.- `@ui` — UI driver (Playwright, RTL, etc.).If unsure, ask the user before generating.## Outputs- `specs/<us-slug>/<rule-slug>.feature` — one per business rule.## HandoffNext: [`spec-review`](../spec-review/SKILL.md) on the generated `.feature` files.## Anti-patterns- **Don't** generate scenarios for rules that are not in `context.md`. Push back, ask `impact-map` to capture them first.- **Don't** invent assertions; every assertion must trace to a rule.- **Don't** mock the system under test in the scenario data. Scenarios describe behavior, not implementation.

Frequently asked questions