spec

Generates a structured feature spec document with acceptance criteria, BDD scenarios, and a working branch from a short idea.

Updated May 26, 2026
One-click install
npx skills add https://github.com/robot-denny/ai-sketchlab --skill spec-robot-denny
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec
Source: https://github.com/robot-denny/ai-sketchlab/tree/main/.agents/skills/spec
Command: npx skills add https://github.com/robot-denny/ai-sketchlab --skill spec-robot-denny

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Turning a rough feature idea into a consistent, plannable specification is slow and error-prone: branch names drift, specs lack acceptance criteria, and downstream planning re-litigates decisions. This Skill converts a short description into a saved, templated spec document with draft BDD scenarios, a classified work type, and a dedicated git branch. ## Core Features & Use Cases - Spec Generation: Derives a Title Case feature title, a git-safe slug, and a branch name from a short idea, then writes a markdown spec following the project's template. - Example Mapping Scenarios: Converts each acceptance criterion into draft Given/When/Then scenarios using Specification by Example and Ubiquitous Language, flagging uncertainties as open questions. - Work-Type Classification: Labels the work as new-capability, change-to, or fix-infra, and creates a draft feature doc skeleton only when a genuinely new capability is introduced. - Use Case: After running a discovery session, pass the increment slug to continue from its discovery.md, or simply describe a new dashboard card component and receive a branch, spec file, and draft feature doc ready for planning. ## Quick Start Ask the assistant to create a spec for a short feature idea, for example: run the spec skill with the argument "card component for dashboard stats".

Frequently Asked Questions about spec

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

FAQPage Schema
How do I turn a feature idea into a written specification?

Provide a short feature description as the argument. The skill derives a title, slug, and branch name, then writes a templated markdown spec with acceptance criteria and draft Given/When/Then scenarios saved to the increment's working directory.

How do I write BDD scenarios from acceptance criteria?

Use Example Mapping: treat each acceptance criterion as a rule, then write concrete Given/When/Then scenarios proving it with real values and business language. Uncertainties discovered while writing scenarios are flagged as open questions.

Can I continue a spec from a discovery document?

Yes. If the argument names an existing increment containing a discovery.md, the skill reuses its slug, title, problem framing, and open questions instead of re-deriving them, preventing duplicate increment directories.

Why does the spec skill abort with uncommitted changes?

The skill requires a clean working tree before creating a branch, so it aborts if uncommitted, unstaged, or untracked files exist. Commit or stash changes first; a discovery.md from a prior exploration should be committed to the base branch.

When is a draft feature doc created during spec writing?

Only when the work is classified as new-capability. Change-to work folds into an existing capability doc during planning, and fix-infra work earns no feature doc, keeping feature docs as evergreen capability records.