How to use the Write Architecture Docs agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. The agent reads those instructions and follows them while working on your request.

This skill is a writing guide, not a tool that changes the system. Once it is loaded, the agent reads at least two sibling docs in the same directory to match their voice, structure and level of detail. It reads the ADRs it plans to reference and summarises their key idea inline, so readers do not have to follow the link to understand the doc.

• Leads with a concrete, complete code snippet, JSON example or diagram near the top of the document.
• Explains why before what, and uses concrete examples.
• Describes the system rather than the project, and avoids words such as PoC, sprint, workstream, milestone and current effort.
• Avoids comparisons with other products or prior versions.
• Orders references: ADRs first, durable reference material second, historical planning docs last and labelled as such.

Install the write-architecture-docs skill

Download the ZIP from the skill's page in this directory, then unzip it. You can install it in one of three places depending on how you use the agent.

For a personal setup available across your projects, unzip the skill into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it: creating, updating or reviewing docs under docs/architecture docs/, or when you ask for documentation that describes the system's design. Ask in plain language and name the file or subsystem where possible.

Because the skill also tells the agent to read sibling docs first, a request that names a directory gives it better context to match.

• Write an architecture doc for the migration subsystem under docs/architecture docs/subsystems/.
• Review this ADR summary and rewrite it so a new engineer can follow it without the link.
• Update the execution pipeline doc to remove the project-status wording.
• Draft a subsystem overview for the contract layer, starting with a grounding example.

Examples of what the output looks like

The skill shapes the document's form. Suppose you ask for an overview of a subsystem. The agent will open with plain language about what the part of the system is and why it exists, then place a concrete snippet near the top with short callouts that point out the key ideas.

When it cites an ADR, the text carries the key idea in a sentence or two and then links the ADR for depth. The rules also ask the agent to state facts about the system rather than narrate how the team got there, so a sentence such as 'The pipeline generalizes across families' is preferred over 'The PoC validated that the pipeline generalizes'.

What it needs, and safety notes

The listing shows no required dependencies. The skill runs no scripts and uses no network access. The only file in the package is SKILL.md, so installing it adds instructions and nothing that executes on your machine.

The skill is written for the Prisma repo. It assumes its folder layout (docs/architecture docs/) and its ADR conventions, so it will fit poorly in other projects. It is also not meant for user-facing Prisma tutorials or marketing copy, because its rules target internal engineering reference docs.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no
• Files: SKILL.md

Tips for getting good results

Give the agent the path to the docs it should match before it starts writing. The skill asks for two sibling docs to be read, so pointing it at a directory saves you a correction round.

Review the output against the skill's quality check: can a newcomer understand each paragraph without outside context, does it explain why before what, and is a concrete example present. Edit any project-status wording the agent misses.

• Name the subsystem directory and any ADRs you want referenced.
• Ask for a grounding example if the draft opens with abstract prose.
• Check that every ADR link resolves from the subsystem doc's location.