skills.rest
alatyshau
alatyshauCOMMUNITY
Explore all skills by this author →
GitHub

spec-architect

Write specification files that serve as source of truth for AI agents.

Updated Nov 21, 2025
Search Tags:#architecture#documentation#markdown#codebase#specification#ai agents#source of truth
One-click install
npx skills add https://github.com/alatyshau/duet --skill spec-architect-alatyshau
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec-architect
Source: https://github.com/alatyshau/duet/tree/main/packages/skills/tools/spec-architect
Command: npx skills add https://github.com/alatyshau/duet --skill spec-architect-alatyshau

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? AI agents lose critical project knowledge when decisions, rationale, and behavioral contracts live only in chat history or are scattered across hundreds of files. This Skill defines how to write specifications that consolidate that knowledge into a durable source of truth, distinct from human-oriented documentation. ## Core Features & Use Cases - Spec Content Rules: Defines what belongs in a spec — glossaries, business rules, architectural boundaries, decisions, rationale, future plans, and behavioral contracts — and what to exclude because a single source already exists (package.json, code signatures, file structure). - Standard File Layout: Establishes a convention of PRODUCT.md, COMPONENT.md, CONTEXT.md, and PROJECT.md per entity type, plus optional DATA_MODEL.md and UI.md companions, with a defined fallback chain for spec discovery. - Anti-pattern Guidance: Prevents duplication of code-derived facts, verbose prose, and human-oriented docs by enforcing concise table-based formats. - Use Case: When an agent might accidentally break a UI default or rename a schema field, a spec written with this Skill records the contract (e.g., "config.json uses snake_case keys") so the agent checks it before changing behavior. ## Quick Start Ask the AI to write a COMPONENT.md spec for the current package following the spec-architect conventions, capturing its architecture, decisions, and behavioral contracts.

Frequently Asked Questions about spec-architect

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

FAQPage Schema
How do I write specifications for AI agents?▼

Write specs that consolidate scattered knowledge, capture decisions and rationale not present in code, and record behavioral contracts that are easy to break. Use concise tables instead of prose, and exclude anything with a single existing source like package.json or type signatures.

What is the difference between a spec and documentation?▼

Specs are source of truth for AI agents, while docs/ is for humans. A spec captures contracts, decisions, and navigation shortcuts an agent needs before changing code; documentation explains the project to people and follows different conventions.

What should go into a COMPONENT.md spec file?▼

COMPONENT.md holds architecture and domain knowledge merged into one file: boundaries, business rules, decisions, and behavioral contracts. Its first sentence becomes the description in the orientation response, and optional DATA_MODEL.md and UI.md companions cover persistence and view behavior.

When should I not write a spec?▼

Do not duplicate information that already has a single source: commands live in package.json, interface signatures in the source files, and file structure is discoverable via Glob. Specs exist only for consolidation, non-code knowledge, contracts, and navigation shortcuts.

How does spec file discovery fallback work?▼

The orientation lookup searches in order: the entity's primary spec file, then COMPONENT.md, then ARCHITECTURE.md, then README.md, then INDEX.md. The first file found wins, so older layouts remain readable during migration.

Related Skills

Explore More Software Engineering Skills→
lsnackermanlsnackerman
42

explore

Search the system to build structured topic reserves with sources.

Community
Advanced
dtabordadtaborda

contract-testing

Validate JSON contract fixtures against Zod schemas with Vitest.

Community
Intermediate
newkayak12newkayak12
1

code-documenter

Generate, format, and validate technical documentation including docstrings and OpenAPI specs.

Community
Intermediate
VitaDynamicsVitaDynamics

adr

Create sequentially numbered Architecture Decision Records in docs/adr/.

Official
Intermediate