# Write Architecture Docs

Write or rewrite architecture subsystem docs, ADRs, and reference material for the...

- Repository: https://github.com/prisma/orm (47661 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add prisma/orm --skill write-architecture-docs -g -a claude-code -y`
Codex: `npx skills add prisma/orm --skill write-architecture-docs -g -a codex -y`
Cursor: `npx skills add prisma/orm --skill write-architecture-docs -g -a cursor -y`
Gemini CLI: `npx skills add prisma/orm --skill write-architecture-docs -g -a gemini-cli -y`

## Description

Write or rewrite architecture subsystem docs, ADRs, and reference material for the engineering team. Use when creating, updating, or reviewing docs under docs/architecture docs/, or when the user asks you to write documentation that describes the system's design.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Writing Architecture Documentation

Architecture docs in this repo serve two audiences: team members working on the system (need precise reference material) and team members seeking context (need an accessible narrative). The doc must work for both without requiring prior project context.

## Before writing

1. **Read at least two sibling docs** in the same directory (e.g., other subsystem docs under `docs/architecture docs/subsystems/`). Calibrate your voice, structure, and level of detail to match them.
2. **Read the ADRs you'll reference.** Don't just link to them, understand them well enough to summarize the key idea inline, so the reader doesn't have to follow the link to understand the doc.

## Voice and framing

**Write about the system, not the project.** These docs describe the intended system as far as we know it. They are not project retrospectives, sprint summaries, or PoC reports.

- State facts: "The execution pipeline generalizes across families", not "The PoC validated that the execution pipeline generalizes"
- No transient project references: avoid "workstream", "PoC", "sprint", "milestone", "being validated", "current effort"
- No product comparisons: don't reference other products or prior versions. Describe what the system *is*, not what it improves upon.
- Non-goals are architectural boundaries, not "not yet done" items. No `(current)` qualifiers.

**Write for a developer without prior context.** Imagine someone joining the team and reading this doc as their first exposure to this part of the system.

The rest: https://github.com/prisma/orm/blob/HEAD/skills-contrib/write-architecture-docs/SKILL.md