# Openspec Authoring

> Enforces OpenSpec authoring conventions including metadata blocks, section ordering, requirement/scenario structure, and validation steps.

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

---


# OpenSpec Authoring Patterns

**Trigger Keywords**: openspec, proposal, change-id, tasks.md, spec delta, requirement, scenario, validation, archive

**Agent Integration**: Used by `spec-writer` and planning agents when creating or updating OpenSpec proposals, tasks, and spec files.

## Metadata & Frontmatter
- Proposals/Tasks: include `Change ID`, `Status`, `Date`, and `Author` near the top.
- Specs: start with `# Spec: <Title>` plus capability/status/related lines.
- Use verb-led, kebab-case `change-id` (e.g., `add-doc-spec-writer-agent`).
- Keep managed instruction blocks intact when present.

## Required Section Ordering
- **proposal.md**: Executive Summary → Background → Goals → Scope/Non-Goals → Approach → Risks & Mitigations → Validation → Open Questions.
- **tasks.md**: Overview → Phase/Task grouping with checklists; include validation notes where possible.
- **spec.md (delta)**: Overview → `## ADDED|MODIFIED|REMOVED Requirements` → Scenarios per requirement with Given/When/Then.

## Requirement & Scenario Patterns
- Each requirement MUST have at least one `#### Scenario:` block.
- Scenario steps use bolded **Given/When/Then** lines on their own lines.
- Keep requirements testable and behavior-focused; avoid solutions in "Then".
- Use backticks for capability or file references when helpful.

## Validation Checklist
- ✅ Run `openspec validate <change-id> --strict` when available.
- ✅ Ensure every referenced skill/agent/capability exists or is added in the change.
- ✅ Confirm paths use workspace-relative notation (`openspec/specs/...`).
- ✅ Keep documentation generic and reusable across Python projects.

## Archiving Notes
- Archive changes only after deployment, using date-prefixed folder under `openspec/archive/`.
- Use `openspec archive <id> --skip-specs --yes` only for tooling-only changes.