diagrams
Skill37 starsChanged 37 days agoMITView on GitHub
Use when creating technical diagrams as code. Covers Mermaid for architecture, sequence, and flow diagrams, choosing the right diagram type, and keeping diagrams accurate as the system changes. Trigger on "draw an architecture diagram", "make a mermaid sequence diagram", "diagram this request flow". Do not use for designing the architecture itself — see the system-design skill.
9 other projects use a version of this.
Adopted by
Most recently taken up by
- Zejnilovic/agdtheir own version, first seen Nov 1, 2026
- AlexCiortan/setlisttheir own version, first seen Oct 29, 2026
- conjurer-rich/skillstheir own version, first seen Oct 25, 2026
- natsukium/claude-code-figures-plugintheir own version, first seen Oct 17, 2026
- roastedbeans/claude-skillstheir own version, first seen Aug 11, 2026
- soujava/agent-skillstheir own version, first seen Jul 13, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- natsukium/claude-code-figures-plugin★ 14same name
- soujava/agent-skills★ 10same name
- Zejnilovic/agd★ 5same name
- HartreeWorks/research-skills★ 4same name
- AlexCiortan/setlist★ 2same name
- conjurer-rich/skills★ 1same name
- mmondora/claude-skills★ 1same name
- gologo13/agent-skills★ 0same name
- roastedbeans/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository137 other files it gives its agents.
- agent-instructionsSkill
- agent-memorySkill
- hooksSkill
- plugin-developmentSkill
- skill-authoringSkill
- skill-reviewSkill
- slash-commandsSkill
- subagentsSkill
- agent-designSkill
- context-engineeringSkill
- fine-tuningSkill
- llm-cost-optimizationSkill
- llm-evaluationSkill
- llm-integrationSkill
- mcp-serverSkill
- ml-pipelineSkill
- model-selectionSkill
- prompt-engineeringSkill
- ragSkill
- structured-outputSkill
- api-designSkill
- background-jobsSkill
- cachingSkill
- djangoSkill
- event-driven-architectureSkill
- fastapiSkill
- graphqlSkill
- microservicesSkill
- nestjsSkill
- realtime-websocketsSkill
- spring-bootSkill
- competitive-analysisSkill
- lead-researchSkill
- product-analysisSkill
- resumeSkill
- user-researchSkill
- database-performanceSkill
- data-modelingSkill
- data-qualitySkill
- pandasSkill
- postgresSkill
- sparkSkill
- brand-guidelinesSkill
- generative-artSkill
- themingSkill
- ui-reviewSkill
- visual-designSkill
- architecture-decisionsSkill
- bug-fix-protocolSkill
- cli-developmentSkill
- code-reviewSkill
- debuggingSkill
- design-patternsSkill
- domain-modelingSkill
- git-workflowSkill
- legacy-modernizationSkill
- refactoringSkill
- repository-explorationSkill
- simple-designSkill
- system-designSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 54
Do not attempt to show every component.
- Distinctive: line 123
Every arrow here is labelled with what actually crosses it.
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagrams
Purpose
Produce technical diagrams as text, so they live in version control, appear in code review, and can be corrected when the system changes — instead of a PNG in a wiki that was accurate two years ago.
When to Use
- Documenting an architecture, a data flow, or a request path.
- Explaining a sequence of interactions between services.
- Visualizing a state machine or a decision flow.
- Adding a diagram to a README, an ADR, or a design document.
Capabilities
- Mermaid: flowcharts, sequence diagrams, state diagrams, ER diagrams, Gantt.
- Diagram-type selection.
- Layout control and readability.
- Rendering to SVG or PNG for contexts that do not support Mermaid.
Inputs
- The system, process, or interaction being described.
- The audience and what they need to understand from it.
Outputs
- A diagram as text, in the repository, next to the code it describes.
- A rendered image, where the destination cannot render Mermaid.
Workflow
- Choose the type by the question — Sequence diagrams answer "what talks to what, in what order". Flowcharts answer "what are the paths through this". State diagrams answer "what states exist and how do you move between them". Using the wrong one produces a diagram that is technically correct and useless.
- Draw one thing — A diagram showing the architecture, the data flow, and the deployment topology at once shows none of them.
- Label the edges — An unlabelled arrow between two boxes conveys almost nothing. "publishes OrderPlaced" conveys a great deal.
- Keep it under about fifteen nodes — Beyond that, it is a map, not a diagram, and nobody will read it.
- Put it in version control — Next to the code. A diagram that is not reviewed alongside the change it describes will drift, silently.
Best Practices
- A diagram that cannot be updated in a pull request will not be updated. That is the entire argument for diagrams-as-code over a drawing tool.
- Unlabelled arrows are the most common diagram defect. The relationship between two components is the information; the boxes are just anchors.
- Trust boundaries, when relevant, should be visible. A diagram that does not distinguish "inside our network" from "the public internet" is missing the thing that matters for a security review.
- Show the failure path, not just the happy one, in a sequence diagram of anything important. The interesting part of a payment flow is what happens when the gateway times out.
- Do not attempt to show every component. A diagram is an abstraction; if it were complete, it would be the code.
- Render to SVG for documentation sites — it scales and the text remains selectable.
Examples
A sequence diagram showing the failure path, which is the part that matters:
sequenceDiagram
autonumber
participant C as Client
participant API as Orders API
participant P as Payments (3rd party)
participant DB as Postgres
participant Q as Outbox → SQS
C->>API: POST /orders (Idempotency-Key)
API->>DB: BEGIN; check idempotency key
alt key already seen
DB-->>API: existing response
API-->>C: 200 (replayed, no double charge)
else new request
API->>P: authorize(amount)
alt authorized
P-->>API: 200 auth_id
API->>DB: INSERT order + INSERT outbox(order.placed); COMMIT
API-->>C: 201 Created
Q->>Q: relay publishes order.placed
else declined
P-->>API: 402 card_declined
API->>DB: ROLLBACK
API-->>C: 402 Payment Required
else timeout (the case that actually hurts)
P--xAPI: no response after 5s
API->>DB: ROLLBACK
API-->>C: 503 + Retry-After
Note over API,P: The charge may or may not have succeeded.<br/>Reconciliation job resolves it against the<br/>gateway within 15 minutes.
end
endThe timeout branch is the one worth diagramming. Everyone understands the happy path.
A flowchart with labelled edges and a visible trust boundary:
flowchart LR
subgraph internet [Public internet]
U[User]
end
subgraph vpc [VPC — private]
direction TB
LB[ALB] -->|"HTTPS, terminated"| API[Orders API]
API -->|"SQL, pooled"| DB[(Postgres)]
API -->|"cache-aside, 5m TTL"| R[(Redis)]
API -->|"publishes via outbox"| SQS[[SQS]]
SQS -->|"at-least-once"| W[Fulfilment worker]
end
U -->|"HTTPS"| LB
API -.->|"outbound, via NAT"| PAY[Payments API]
style internet fill:#fee2e2,stroke:#dc2626
style vpc fill:#f0fdf4,stroke:#16a34aNotes
- Every arrow here is labelled with what actually crosses it. The unlabelled version of this diagram — the same boxes, plain arrows — conveys roughly a tenth as much.
- Mermaid renders natively on GitHub, GitLab, and most documentation platforms. A diagram in a Markdown file is reviewed in the pull request alongside the code it describes, which is the only mechanism that keeps diagrams true.
- For a diagram that must be pixel-precise or heavily styled, Mermaid will frustrate you. Use it for the 95% of diagrams where accuracy and maintainability matter more than aesthetics.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

