spec-create

Draft or update functional product contracts in spec.md from approved ideas.

2|Updated Mar 27, 2026

Search Tags:#acceptance criteria #docs #product spec #enhancement delta #functional contract #workflow dossier

Ready to run

npx skills add https://github.com/bdemarzo/ai-workflows --skill spec-create-bdemarzo

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: spec-create
Source: https://github.com/bdemarzo/ai-workflows/tree/main/skills/spec-create
Command: npx skills add https://github.com/bdemarzo/ai-workflows --skill spec-create-bdemarzo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve?

It helps you convert an approved idea into a precise, user-visible functional product contract so planning and engineering can proceed with clarity instead of ambiguity.

Core Features & Use Cases

Drafts and updates spec.md: Creates or refines ./docs/workflows/{slug}/spec.md as the Product Manager operator’s source-of-truth contract.
Produces a contract, not a plan: Separates product requirements and acceptance behavior (spec) from sequencing and mechanics (plan).
Supports new work and enhancements: For enhancements, it captures Current/Changed/Preserved behavior and clear acceptance for both the delta and regressions.

Quick Start

Use the spec-create skill to draft or update ./docs/workflows/{slug}/spec.md from an approved idea so the result is ready for spec-review.

Frequently Asked Questions about spec-create

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

FAQPage Schema

How do I write a functional product spec from an approved idea?▼

To write a functional product spec from an approved idea, draft a user-visible product contract in spec.md that defines correctness and acceptance criteria while omitting implementation mechanics. This creates a self-contained functional contract ready for planning.

What is a functional contract versus an implementation plan in product management?▼

A functional contract defines user-visible product requirements and acceptance behavior, whereas an implementation plan details sequencing and technical mechanics. Separating the spec from the plan ensures engineering proceeds with clarity on expected outcomes rather than build steps.

How do I document enhancement deltas for an existing product spec?▼

To document enhancement deltas in an existing spec, update the functional contract to capture Current, Changed, and Preserved behaviors. You must define clear acceptance criteria for both the enhancement delta and potential regressions to maintain source consistency.

How do I structure a workflow dossier spec for planning?▼

Structure a workflow dossier spec by creating or updating ./docs/workflows/{slug}/spec.md in place. Enforce the exact H1 format and keep the spec self-contained for planning by deriving the slug and preserving dossier slug relationships.

Can I update a spec.md file to incorporate spec-review outcomes?▼

Yes, you can update spec.md to incorporate accepted spec-review outcomes. Refining the existing contract preserves dossier slug relationships and contract-source consistency while ensuring the functional product contract remains accurate for the Product Manager operator.

When should I exclude implementation mechanics from a product spec?▼

You should exclude implementation mechanics from a product spec whenever drafting or updating the functional contract. The spec must contain only user-visible correctness and acceptance criteria, intentionally omitting technical sequencing to separate requirements from the plan.