skills.rest
fx
fxCOMMUNITY
Explore all skills by this author →
GitHub

spec-writer

Writes and maintains living specs and change documents in a docs tree.

Updated Nov 2, 2025
Search Tags:#documentation#specification#requirements traceability#technical writing#docs#change management#rfc 2119
One-click install
npx skills add https://github.com/fx/skills --skill spec-writer-fx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec-writer
Source: https://github.com/fx/skills/tree/main/skills/spec-writer
Command: npx skills add https://github.com/fx/skills --skill spec-writer-fx

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Keeping technical specifications synchronized with an evolving codebase is difficult, and planning documents often drift from the actual implementation. This Skill manages the full specification lifecycle: creating living specs in docs/specs/, auditing them against real code, identifying gaps, and proposing change documents in docs/changes/ to close those gaps. ## Core Features & Use Cases - Living Spec Management: Creates one spec per major feature area using RFC 2119 keywords and GIVEN/WHEN/THEN scenarios, with mandatory changelogs and single-owner contracts that prevent duplicated behavioral rules. - Implementation Audits: Launches parallel exploration agents to compare spec claims against actual code, categorizing divergences as outdated, aspirational, or undocumented behavior. - Change Document Planning: Generates sequentially numbered change documents with tasks, dependencies, and testing requirements that reference specs instead of restating them. - Duvet Traceability Mode: When a .duvet/ directory exists, assigns globally unique REQ-NNN IDs to new requirements, confines keywords to requirement sections, and verifies extraction with the duvet CLI. - Use Case: Ask the agent to spec out a new authentication feature; it researches the codebase, writes docs/specs/authentication/index.md, and proposes change documents for any unimplemented behavior. ## Quick Start Ask the agent to write a spec for the password reset feature and propose change documents for anything not yet implemented.

Frequently Asked Questions about spec-writer

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

FAQPage Schema
How do I write a technical specification that stays in sync with code?▼

Create one living spec per major feature in docs/specs/ describing current observable behavior with RFC 2119 keywords and GIVEN/WHEN/THEN scenarios. Audit the spec against the codebase regularly and log every update in the spec's changelog.

How do I plan implementation work from an existing spec?▼

Create sequentially numbered change documents in docs/changes/ that reference the spec sections owning the behavior rather than restating them. Each change document owns sequencing, migrations, design decisions, tasks, and testing requirements.

Can this skill write implementation code along with the spec?▼

No, the skill is strictly documentation-only and must not create or modify any file outside the docs/ tree. If implementation is requested, it writes the spec first and directs the user to a separate implementation workflow.

What is duvet mode in requirements traceability?▼

When a .duvet/ directory exists at the repository root, every new requirement gets a globally unique REQ-NNN heading, exactly one self-contained normative sentence, and RFC 2119 keywords confined to requirement sections so the duvet CLI can trace each requirement to code.

Why should a spec avoid naming library APIs in requirements?▼

Naming components, methods, or props in a normative rule turns a third-party API into a claim reviewers must re-verify forever, and it goes stale on every upgrade. Specs should state observable behavior; library choices belong in change document design decisions.

Related Skills

Explore More Software Engineering Skills→
RuixeWolfRuixeWolf
4

openspec-explore

Explores ideas and investigates codebases to clarify requirements before creating OpenSpec change proposals.

Community
Intermediate
MetaMaskMetaMask
3.0k

pr-changelog

Generate a CHANGELOG entry line from pull request code changes.

Official
Intermediate
gittowergittower
413

ship-issue

Resolve small GitHub issues end to end through merged pull requests.

Official
Advanced
harleypigharleypig
3

write-documentation

Generate README, API references, and changelogs from source code.

Community
Advanced