About explaining-architecture
A read-only skill for explaining unfamiliar code subsystems through architecture, execution flow, and gotchas. It is intended for engineers seeking a practical mental model, and routes questions about design motivation or history to a separate skill when available.
Key features
- 01Architecture and flow explanations
- 02Traces behavior from implementation
- 03Cites claims with file and line
- 04Separates mechanics from design rationale
- 05Read-only; changes no state
Use cases
- 01Understand an unfamiliar subsystem
- 02Trace a feature from trigger to effect
- 03Locate where validation belongs
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/explaining-architecturein Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
agents/openai.yamlreferences/critique-mode.mdshared/docs-vs-code.mdskill-calls.mdDetails
From the project READMEExplaining architecture
Answer "how does X work?" with the mental model a senior engineer needs to start working in an unfamiliar subsystem: its architecture, flow, and sharp edges, not annotated source code.
When the question is about motivation, rejected alternatives, or history
rather than mechanics, call the Skill tool with
investigating-design-rationale instead. If that skill is not installed, say
so and answer the mechanics only. Without a Skill tool, follow the
skill call rules.
The skill is read-only: it writes no files and changes no state. Describe what the code does, not what its docs claim, and report any disagreement per the docs and code rules.
Input
The request names a subsystem, a feature flow, or a placement question ("where should this validation live"). When it names none or is vague, infer the target from conversation context and state your interpretation in one line before exploring. Do not ask first.
Explain
Read the implementation; never infer behavior from file or function names.
Trace each flow from trigger to effect. Where you cannot trace a link, say so
instead of inventing it. Claims about code carry file:line, and a flow step
names the function that runs it.
Adapt the answer to the question; use only the sections it needs:
- Overview: what it is, what it does, why it exists, in a paragraph or two.
- Key Concepts: the abstractions needed to follow the rest.
- How It Works: trigger, steps, data movement, decision points, in prose. Add a mermaid diagram only when the flow crosses several components.
- Where Things Live: the file map someone needs to start, not every file.
- Gotchas: surprising behavior, historical residue, sharp edges.
When something is complex, explain why. Leave out how you explored, background the question did not raise, and restatement.
Critique
Run only when the request asks for problems, issues, or improvements. Finish the explanation first, then follow critique mode.