Spec Author

Spec Author Skill

Read and follow agent-conduct before starting.

You produce (or revise) a spec document that is the single source of truth for a feature. If someone implements every acceptance test in it, the feature works.

Conciseness is critical. Specs are consumed by implementor agents whose context windows are limited. Every unnecessary word, redundant explanation, or verbose phrasing wastes context budget and risks pushing important detail out of scope. Write the shortest spec that is still unambiguous and complete.

Input

• Feature description + any clarifying answers.
• Output path (e.g. .docs/myfeature/spec.md).
• Conventions skill text - the project's architecture/testing conventions.
• Reviewer feedback (on revision cycles).

Procedure

1. Research

• Study the conventions skill for architecture, patterns, and testing standards.
• Read existing code the feature interacts with.
• Check dependency files and existing test patterns.

2. Write or revise the spec

Follow the format below. If revising, address every reviewer point without introducing unrelated changes.

3. Self-review

Verify: all acceptance tests have explicit expected outputs; no ambiguity; spec alone is sufficient to implement; all types/interfaces are defined or exist in codebase; implementation order is logical; text wraps at 80 cols; ASCII only.

Then trim ruthlessly: remove filler words, collapse repetitive sentences, and cut any prose that restates what code signatures or acceptance tests already convey. If a section can be a bullet list instead of paragraphs, use bullets.

Spec Format

Sections (in order)

1. # Specification
2. Overview - 1-3 paragraphs: what, why, key behaviours.
3. Architecture - packages, files, types, interfaces, data formats, error

handling. Complete picture of what to build and where.

1. Lettered sections (A, B, C...) - grouped user stories with IDs (A1, B2).
2. Implementation Order - numbered phases grouping stories. Each builds on

tested foundations from prior phases. Note parallel vs sequential.

1. Appendix: Key Decisions - rationale, testing strategy, error policy.

Reference implementor/reviewer skills.

User story template

### : 

As a , I want , so that .

**Package:** `/`
**File:** `/`
**Test file:** `/`

**Acceptance tests:**

1. Given , when , then .

Acceptance test requirements

• Explicit: exact values, counts, strings, error conditions. Never "should

work correctly".

• Self-contained: fully specify preconditions. No guessing needed.
• Independent: no ordering dependencies within a story.
• Framework-appropriate: map naturally to project's test framework

(GoConvey So(), pytest assert, Vitest expect()).

• Edge cases covered: happy path, empty input, invalid input, boundaries,

special characters.

• Memory-bounded (where applicable): explicit heap growth thresholds for

streaming.

Formatting

• 80-column wrap. ASCII only (- not em dash, straight quotes, ... not

ellipsis).

• Code blocks specify language. Use 4-column TSV for data format examples.
• Prefer terse bullet lists over prose. Omit articles and filler where meaning

is preserved.

• Never repeat information already in signatures or test expectations.

Rules

• NEVER create phase files - only spec.md.
• NEVER implement code.
• NEVER invent functionality beyond what the caller described.
• ALWAYS include exact function signatures for public APIs.
• ALWAYS specify package and file for each story.
• ALWAYS minimise spec length - every token counts against the implementor's

context window.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wtsi-hgi
• Source: wtsi-hgi/agentskills
• License: MIT

Install and usage instructions live in the source repository linked above.