What is the difference between spec.md and design.md?

The spec.md file focuses on 'what' the system does using functional requirements, while design.md explains 'how' and 'why' through architecture, rationale, and diagrams.

What happens when I use the --review flag?

Claude spawns a specialized 'team' consisting of a spec-writer and an architect agent to cross-review the documentation for accuracy and compliance.

How does the skill use RFC 2119?

It ensures all normative statements in the specification use standardized keywords like SHALL, MUST, and SHOULD to eliminate ambiguity in requirements.

Does it support visual diagrams?

Yes, every design document generated includes at least one Mermaid diagram, such as a C4 container diagram, sequence flow, or ERD.

OpenSpec Architect

Name: OpenSpec Architect
Author: joestump

byjoestump

•

Learning & Documentation

Standardizes technical documentation by generating paired functional requirement specifications and architectural design records.

The spec skill automates the creation of high-quality technical documentation by enforcing the OpenSpec standard within your project. It generates synchronized spec.md and design.md files, ensuring a strict alignment between functional requirements (the 'what') and architectural rationale (the 'how'). By utilizing RFC 2119 normative language and automated Mermaid diagram generation, this skill helps engineering teams maintain a rigorous, searchable, and consistent source of truth for system architecture. It supports both single-agent drafting and a multi-agent 'team review' mode to ensure all specifications meet high-quality standards before finalization.

Key Features

01Generates synchronized requirements (spec.md) and architectural design (design.md) pairs

02Enforces RFC 2119 normative language for precise, industry-standard requirements

03Automatically creates Mermaid diagrams for system architecture and data flows

04Offers a collaborative team-review mode with specialized Writer and Architect agents

05Provides seamless integration with ADRs and project-wide CLAUDE.md context

064 GitHub stars

Use Cases

01Formalizing a rough idea or feature request into a structured technical specification

02Converting existing Architecture Decision Records (ADRs) into detailed implementation specs

03Conducting automated architectural reviews to ensure design consistency across a codebase

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add joestump/claude-plugin-design spec

For use in Claude.ai and ChatGPT

Download Skill