1. Where It Fits
- Before implementation, when the ticket is still ambiguous.
- Before PR review, when generated code needs evidence.
- Before API rollout, when consumers need a clear contract.
- After incidents, when the team needs a spec gap analysis.
Spec-first AI workflow
Spec Skills for Spec-First Workflows
Spec Skills is most useful when it is treated as a constrained drafting and review workspace, not as a general chat box. Give it a ticket, a template, and review rules; expect a spec draft, acceptance criteria, risks, and open questions that a human can approve or reject.
Use case: structure before implementation
2. Inputs to Provide
- The original ticket or PRD excerpt.
- The template fields the output must follow.
- Known non-goals, dependencies, and owners.
- Existing API/schema snippets when contract behavior matters.
3. Outputs Worth Keeping
- A scoped spec draft with explicit open questions.
- Given/When/Then acceptance criteria.
- A risk register with owner, likelihood, impact, and mitigation.
- A reviewer checklist tied to release evidence.
4. Human Review Boundary
- Spec Skills can draft; it should not approve scope.
- It can propose risks; owners still accept or reject them.
- It can summarize contract diffs; engineers still decide compatibility.
- It can produce test ideas; failing evidence still blocks release.
5. When Not to Use It
- When product ownership is unresolved.
- When the input contains secrets or regulated data.
- When the team wants approval without review.
- When the task is small enough for a short checklist.
6. Adoption Test
After two weeks, compare three signals: fewer clarification comments, clearer acceptance tests, and fewer PR review surprises. If those do not improve, narrow the workflow before adding more automation.
Ticket to Reviewable Spec
A strong Spec Skills workflow starts with a bounded artifact and ends with something reviewers can mark up. The output should not be a polished essay. It should be a draft with decisions, assumptions, missing inputs, and tests.
Input: - Ticket: "Add bulk user disable for workspace admins" - Template: feature-spec.md - Required sections: goal, non-goals, roles, API behavior, audit log, rollback, acceptance criteria Expected Spec Skills output: - Spec draft with unresolved questions called out - 8-12 Given/When/Then acceptance criteria - Risk register for permission mistakes, partial failures, and audit gaps - Reviewer checklist for product, backend, QA, and support
Editorial note: this page focuses on how Spec Coding would use Spec Skills inside a spec-first delivery process. Adapt these patterns to your team before adoption.
1. Prompt Boundaries
- Name the source material Spec Skills may use.
- Forbid invented requirements and hidden implementation choices.
- Require every assumption to appear in an "open questions" list.
- Keep output in the template your team already reviews.
2. Reviewable Output
- Spec: goal, non-goals, decisions, API/data impact.
- Acceptance criteria: happy path, failure path, boundary path.
- Risk register: owner, mitigation, evidence, rollback trigger.
- Questions: items that block implementation until answered.
3. Team Controls
- Store approved prompts in the repository.
- Keep specs as Markdown so the tool can be replaced later.
- Require PR evidence for generated code.
- Log which prompt version produced the draft.
4. Adoption Decision
Adopt Spec Skills only when it improves the artifact reviewers already need. If the team gets more text but not clearer decisions, the workflow is too broad. Narrow the task to one repeatable handoff and measure whether review comments become more specific.
The useful question is not whether the draft sounds good. It is whether another engineer can implement from it with fewer clarifying messages.
Adoption Checklist
Choose one workflow first: ticket to spec, API diff to review note, incident to postmortem seed, or acceptance criteria rewrite. Do not automate the whole delivery process on day one.
What to Measure After Two Weeks
Track whether specs need fewer clarification comments, whether QA can derive tests earlier, whether generated PRs include evidence, and whether reviewers find missing risks before implementation.
When to Pause
Pause adoption when outputs invent requirements, hide unresolved questions, bypass product/security review, or cannot be traced back to a prompt and source artifact.
Source Gate
Before running a workflow, list the exact source artifacts Spec Skills may use: ticket URL, product note, existing spec, API schema, error table, or incident timeline. If a requirement is not in one of those sources, the output should label it as an assumption rather than presenting it as approved scope.
Output Gate
Before accepting the draft, check that every section maps to a reviewer action. Product should be able to approve scope, engineering should be able to inspect API or data behavior, QA should be able to derive tests, and support should see customer-visible failure states.
Release Gate
Before generated code ships, require evidence tied back to the spec: passing tests, API diff review, migration rollback notes, feature flag state, and the metric or alert that proves the workflow is healthy after deployment.
Is Spec Skills a replacement for a technical spec?
No. It can draft and critique the spec, but the approved artifact still needs human ownership, version history, and test evidence.
What should the first workflow be?
Start with a narrow ticket-to-spec workflow. It has clear inputs, a visible output, and obvious review questions, so the team can judge quality quickly.
How do you keep output from becoming generic?
Require source references, explicit assumptions, concrete examples, and a rejection pass for vague words such as "fast", "robust", "simple", and "seamless".
Use Spec Skills With a Spec Boundary
Pair Spec Skills with a reusable template and a review checklist. That keeps AI output close to the decisions the team actually has to approve.
Spec Skills is a Spec Coding workflow lens, not a third-party product guarantee. Use the patterns here as reusable review habits.