writing-spec

Synthesizes design discussions into reviewed spec documents with user approval gating.

Updated Mar 18, 2026
One-click install
npx skills add https://github.com/pgoell/pgoell-claude-tools --skill writing-spec-pgoell
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-spec
Source: https://github.com/pgoell/pgoell-claude-tools/tree/main/plugins/workbench/skills/writing-spec
Command: npx skills add https://github.com/pgoell/pgoell-claude-tools --skill writing-spec-pgoell

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? After a design brainstorm, decisions live only in conversation history and are easily lost or misremembered when implementation planning begins. This Skill converts an approved design discussion into a written spec document, verifies it with an independent reviewer, and gates on user approval before any planning starts. ## Core Features & Use Cases - Spec drafting: Synthesizes the discussion into a structured spec covering problem, solution, user stories, implementation decisions, testing, out-of-scope items, and risks, written to a resolved path such as .workbench/specs/. - Fresh-eyes self-review: Dispatches a general-purpose subagent that has not seen the conversation to adversarially check the spec for placeholders, contradictions, ambiguity, and scope problems, then applies fixes inline. - Approval gate and handoff: Presents the spec for user approval, commits it when the path is committable, and recommends workbench:writing-plans as the next step without invoking implementation itself. - Use Case: After a brainstorming session on a new caching layer, invoke this Skill to produce 2025-01-15-caching-layer-design.md, have it adversarially reviewed, approve it, and move straight into implementation planning. ## Quick Start Turn our approved design discussion into a spec document and review it before we start planning.

Frequently Asked Questions about writing-spec

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

FAQPage Schema
How do I turn a design discussion into a spec document?

Invoke the Skill after the design is approved in discussion. It drafts a spec covering problem, solution, user stories, implementation decisions, testing, out-of-scope items, and risks, writes it to the resolved specs path, and runs a self-review before asking for your approval.

When should I write a spec versus keep brainstorming?

Write a spec only when the discussion is far enough along that the document is a synthesis, not another round of questions. If you are still exploring approaches or asking open questions, return to brainstorming first and invoke the spec step afterward.

Can the spec be output as HTML instead of Markdown?

Yes. Markdown is the default, but a per-prompt phrase like "an HTML spec" or a config entry overrides it. HTML output follows the bundled template and can inline a named design system's colors, typography, components, and images.

What does the spec self-review subagent check?

The reviewer subagent reads only the spec file and adversarially checks completeness, internal consistency, clarity, scope, and unrequested additions. It must cite concrete planning failures for each issue, and its findings are applied inline without a re-review loop.

Where are spec files saved and are they committed?

The path resolves from the pilot file's Specs heading, then project instruction files, then the default `.workbench/specs/` directory. If the resolved value is "don't commit", the spec goes to a temp directory and the commit step is skipped.