| name | spec-authoring |
| description | Standard for authoring engineering behavior-contract specs in docs/specs/: scope subsystems, assign stable IDs, structure docs, manage lifecycle. |
| version | 1.0.0 |
| category | documentation |
| agent_types | ["engineer","documentation"] |
| tags | ["specification","spec","authoring","engineering","standards"] |
| effort | medium |
| user-invocable | true |
| progressive_disclosure | {"entry_point":{"summary":"Author engineering specs in docs/specs/ using the SPEC-{SUBSYSTEM}-{NN}~{rev} grammar, a behavior-contract template, and a defined lifecycle. Specs are engineering-owned and implement PRD requirements.","when_to_use":"When creating a new docs/specs/{subsystem}.md file, adding spec sections, deciding granularity, establishing a new subsystem, or running pre-spec technical research.","quick_start":"1. Read docs/specs/README.md for ID grammar 2. Pick/create the subsystem file 3. Apply the spec template 4. Cite the PRD requirement realized 5. Link implementing modules 6. Run the CI traceability check"},"references":["spec-template.md","category-taxonomy.md","granularity-guide.md","research-conventions.md","authoring-workflow.md"]} |
Spec Authoring
Overview
This skill is the agent-facing entry point to the Engineering Spec Authoring Standard:
how to write engineering specifications in docs/specs/. A spec is a behavior contract
(testable WHAT + WHY, linked to implementing modules), owned by Engineering / Architecture.
It has two distinct companions — keep the roles separate:
spec-authoring (this skill) = authoring engineering specs. Scope a subsystem into a
file, assign stable IDs, structure a behavior-contract document, decide granularity, run
pre-spec technical research, and move a spec through its lifecycle.spec-linked-docs (SLD) = traceability. Keep source code in sync with the spec via
docstring References and a CI checker.prd-authoring = product PRDs (a separate, product-owned standard — docs/prd/).
SPEC ≠ PRD. A SPEC is an engineering contract (SPEC-{SUBSYSTEM}-{NN}~{rev}, in
docs/specs/, owned by Engineering). A PRD is a product requirements doc
(PRD-{AREA}-{NN}, in docs/prd/, owned by Product). A spec implements a PRD
requirement and cites it; product framing (problem, users, acceptance criteria, metrics)
stays in the PRD. Do not put PRD content in a spec.
Full standard: docs/specs/AUTHORING.md.
This skill orients and links; AUTHORING.md is the authoritative, portable standard.
The ID grammar itself lives in docs/specs/README.md
— defer to it; never re-derive it.
Use this skill, do not duplicate it. SKILL.md is a concise router. The detailed rules
live in AUTHORING.md and the five reference files below. Read the reference you need.
When to Use
- Creating a new
docs/specs/{subsystem}.md file for a subsystem.
- Adding a governed
SPEC-{SUBSYSTEM}-{NN}~{rev} section to an existing spec.
