# Spec Writer

> Skill: Specification Writing (Cross-Cutting)

- Skill: `polyxgo/spec-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add polyxgo/spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/polyxgo/spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: PolyXGO (https://skillmd.com/u/polyxgo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/polyxgo/spec-writer

---

# Skill: Specification Writing (Cross-Cutting)

## Purpose

Write and refine high-quality functional/technical specifications, user stories, and delta specs for consumption by AI agents.

## When to Use

- When starting a new feature change (Step 1 of the HeraSpec workflow)
- When converting high-level business ideas into structured technical specs
- When refining delta specs during parallel merge validation

## Step-by-Step Process

### Step 1: Define User Story & Scenarios
- Structure the core requirement as a User Story (As a... I want to... So that...)
- Formulate behavioral scenarios using GIVEN-WHEN-THEN syntax (Gherkin style)
- Define happy paths, error paths, and edge cases

### Step 2: Structure metadata
- Specify target components, domains, and technical stacks
- Verify requirements match the architectural conventions defined in `project.md`

### Step-3: Write Delta Spec
- Segment new, modified, and removed requirements clearly:
  - `## ADDED Requirements`
  - `## MODIFIED Requirements` (must specify the exact Before vs. After states)
  - `## REMOVED Requirements`

## Required Input

- Business requirement description or user prompt
- Technical stack metadata from `project.md`

## Expected Output

- Clean markdown specification following the HeraSpec format
- Complete Delta Spec with GIVEN-WHEN-THEN scenarios

## Tone & Rules

- Be extremely precise. Avoid ambiguous language like "user-friendly" or "fast".
- Always define exact failure states (e.g. "returns 401 Unauthorized" instead of "shows error").
- Scenarios MUST be testable and actionable.

## Available Templates

- None

## Available Scripts

- None

## Examples

See `examples/` directory.

## Links to Other Skills

- **documents**: Use to format the specifications into product manuals.
- **suggestion**: Use to identify gaps in existing specs.