ported/20260305-085418/core-tools/skills/technical-diagrams/SKILL.md
Provides Mermaid diagram syntax, best practices, and styling rules for technical visualizations. Use when creating diagrams, flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, architecture diagrams, C4 diagrams, visualizations, or any visual documentation in markdown. Always use this skill when generating or updating Mermaid code blocks.
npx skillsauth add sequenzia/agent-alchemy technical-diagramsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Mermaid is the standard for all technical diagrams in this project. It renders natively in GitHub, GitLab, MkDocs (with Material theme), and most modern documentation platforms.
This skill provides:
Always wrap Mermaid code in fenced code blocks with the mermaid language identifier.
Native rendering — GitHub, GitLab, Notion, MkDocs, and Docusaurus render Mermaid blocks without plugins or build steps. No external image generation tools needed.
Text-based and diffable — Diagrams live alongside code in version control. Changes appear in pull request diffs, making reviews straightforward and history trackable.
No external tools — No Lucidchart exports, no draw.io XML files, no PNG screenshots that go stale. The diagram source is the single source of truth.
Maintainable — Updating a diagram means editing text, not wrestling with a GUI. Refactoring a component name? Find-and-replace works on diagrams too.
Consistent — A shared syntax produces visually consistent diagrams across all documentation, regardless of who authored them.
This is the most important section. Light text on light backgrounds is the most common Mermaid readability issue. Follow these rules strictly.
Every node must have color:#000 (or another dark color like #1a1a1a, #333). Never use white, light gray, or any light-colored text.
classDef for consistent stylingDefine reusable styles at the bottom of the diagram and apply them with ::: syntax:
flowchart LR
A[Input]:::primary --> B[Process]:::secondary --> C[Output]:::success
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
Use these pre-tested combinations that guarantee readability:
| Style Name | Fill | Stroke | Text | Use For |
|-----------|------|--------|------|---------|
| primary | #dbeafe | #2563eb | #000 | Main components, entry points |
| secondary | #f3e8ff | #7c3aed | #000 | Supporting components |
| success | #dcfce7 | #16a34a | #000 | Success states, outputs |
| warning | #fef3c7 | #d97706 | #000 | Warnings, caution areas |
| danger | #fee2e2 | #dc2626 | #000 | Errors, critical items |
| neutral | #f3f4f6 | #6b7280 | #000 | Background, inactive items |
Bad — light text is invisible on light background:
classDef bad fill:#dbeafe,stroke:#2563eb,color:#93c5fd
Good — dark text is always readable:
classDef good fill:#dbeafe,stroke:#2563eb,color:#000
| Diagram Type | Mermaid Keyword | Use Case | Reference |
|-------------|----------------|----------|-----------|
| Flowchart | flowchart | Process flows, decision trees, pipelines | See Flowcharts section below |
| Sequence | sequenceDiagram | API interactions, message passing, protocols | See references/sequence-diagrams.md |
| Class | classDiagram | Object models, interfaces, relationships | See references/class-diagrams.md |
| State | stateDiagram-v2 | State machines, lifecycle management | See references/state-diagrams.md |
| ER | erDiagram | Database schemas, entity relationships | See references/er-diagrams.md |
| C4 | C4Context / C4Container / etc. | System architecture, containers, components | See C4 Diagrams section below |
Minimal copy-paste examples for simple diagrams. For complex use cases, load the corresponding reference file.
flowchart TD
A[Start]:::primary --> B{Decision}:::neutral
B -->|Yes| C[Action A]:::success
B -->|No| D[Action B]:::warning
C --> E[End]:::primary
D --> E
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef warning fill:#fef3c7,stroke:#d97706,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
sequenceDiagram
participant C as Client
participant S as Server
participant D as Database
C->>S: POST /api/resource
activate S
S->>D: INSERT INTO resources
D-->>S: OK
S-->>C: 201 Created
deactivate S
classDiagram
class Service {
-repository: Repository
+create(data: CreateDTO): Entity
+findById(id: string): Entity
}
class Repository {
<<interface>>
+save(entity: Entity): void
+findById(id: string): Entity
}
Service --> Repository : uses
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Approved : approve
Review --> Draft : reject
Approved --> Published : publish
Published --> [*]
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : "appears in"
USER {
int id PK
string email UK
string name
}
ORDER {
int id PK
int user_id FK
date created_at
}
C4Context
title System Context Diagram
Person(user, "User", "End user of the system")
System(system, "Application", "Main system under design")
System_Ext(ext, "External API", "Third-party service")
Rel(user, system, "Uses", "HTTPS")
Rel(system, ext, "Calls", "REST API")
classDef — Reusable Style ClassesDefine once, apply to many nodes:
flowchart LR
A[Node A]:::primary --> B[Node B]:::secondary
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
::: Shorthand — Apply Class InlineA[Label]:::className
style — One-Off Inline StylingFor single-node overrides (prefer classDef for consistency):
style nodeId fill:#dbeafe,stroke:#2563eb,color:#000
Define these at the bottom of any diagram that uses multiple styles:
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef warning fill:#fef3c7,stroke:#d97706,color:#000
classDef danger fill:#fee2e2,stroke:#dc2626,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
Subgraphs can be styled via style directives:
flowchart LR
subgraph backend["Backend Services"]
A[API]:::primary --> B[Worker]:::secondary
end
style backend fill:#f8fafc,stroke:#94a3b8,color:#000
linkStyleStyle specific edges by their index (0-based, in order of definition):
linkStyle 0 stroke:#2563eb,stroke-width:2px
linkStyle 1 stroke:#dc2626,stroke-width:2px,stroke-dasharray:5
Limit to 15-20 nodes maximum. If a diagram grows beyond that, split it into multiple diagrams or use subgraphs to manage complexity.
A[User Service] --> B[Auth Service] %% Good: descriptive
A --> B %% Bad: meaningless
A -->|validates| B %% Good: explains the relationship
A --> B %% Acceptable only if the relationship is obvious
Use subgraphs to visually separate layers, domains, or subsystems:
flowchart TD
subgraph frontend["Frontend"]
A[React App]:::primary
end
subgraph backend["Backend"]
B[API Server]:::secondary --> C[Database]:::neutral
end
A --> B
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
Within a single diagram, stick to one arrow style unless you need to distinguish different relationship types:
--> solid arrow (primary flow)-.-> dotted arrow (optional or async)==> thick arrow (critical path)flowchart over graphflowchart is the modern syntax with more features (subgraph styling, ::: shorthand, more shapes). graph is legacy — use flowchart for all new diagrams.
pymdownx.superfences with custom Mermaid fence configSimple diagrams — The quick reference above is sufficient. Use it for:
Complex or unfamiliar diagrams — Load the reference file when:
C4 diagrams — Always consult the C4 Diagrams section below. C4 uses a unique function-call syntax (Person(), System(), Container(), etc.) that differs significantly from other Mermaid diagrams.
Flowcharts visualize process flows, decision trees, pipelines, and system architectures. They are the most versatile Mermaid diagram type.
Keyword: flowchart (prefer over legacy graph)
| Keyword | Direction | Best For |
|---------|-----------|----------|
| TD / TB | Top to bottom | Hierarchies, process steps |
| LR | Left to right | Pipelines, request flows, timelines |
| BT | Bottom to top | Dependency trees |
| RL | Right to left | Rarely used |
flowchart LR
A --> B --> C
| Syntax | Shape | Use For |
|--------|-------|---------|
| A[Text] | Rectangle | Default, general purpose |
| A(Text) | Rounded rectangle | Processes, steps |
| A([Text]) | Stadium | Start/end points |
| A[[Text]] | Subroutine | External processes |
| A[(Text)] | Cylinder | Databases, storage |
| A((Text)) | Circle | Connectors, small nodes |
| A{Text} | Diamond | Decisions, conditions |
| A{{Text}} | Hexagon | Preparation steps |
| A>Text] | Asymmetric | Flags, signals |
| A[/Text/] | Parallelogram | Input/output |
| A[\Text\] | Alt parallelogram | Alt input/output |
| A[/Text\] | Trapezoid | Transforms |
| A[\Text/] | Alt trapezoid | Alt transforms |
| A(((Text))) | Double circle | Critical nodes |
| Syntax | Description |
|--------|-------------|
| A --> B | Arrow |
| A --- B | Line (no arrow) |
| A -->\|label\| B | Arrow with label |
| A --label--> B | Arrow with label (alt) |
| Syntax | Description |
|--------|-------------|
| A -.-> B | Dotted arrow |
| A -.- B | Dotted line |
| A -.->\|label\| B | Dotted arrow with label |
| Syntax | Description |
|--------|-------------|
| A ==> B | Thick arrow |
| A === B | Thick line |
| A ==>\|label\| B | Thick arrow with label |
| Syntax | Description |
|--------|-------------|
| A <--> B | Bidirectional arrow |
| A o--o B | Circle endpoints |
| A x--x B | Cross endpoints |
Add extra dashes/dots/equals to make edges longer:
A ---> B (longer than A --> B)A -----> B (even longer)Group related nodes into labeled regions:
flowchart TD
subgraph frontend["Frontend Layer"]
A[React App] --> B[State Manager]
end
subgraph backend["Backend Layer"]
C[API Server] --> D[Database]
end
B --> C
flowchart TD
subgraph cloud["Cloud Infrastructure"]
subgraph compute["Compute"]
A[App Server]
end
subgraph storage["Storage"]
B[Object Store]
end
end
A --> B
Override direction inside a subgraph:
subgraph section["Section"]
direction LR
A --> B --> C
end
flowchart LR
A[Input]:::primary --> B[Process]:::secondary --> C[Output]:::success
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
style A fill:#dbeafe,stroke:#2563eb,color:#000
style subgraphId fill:#f8fafc,stroke:#94a3b8,color:#000
Style edges by their 0-based index (order of definition):
linkStyle 0 stroke:#2563eb,stroke-width:2px
linkStyle 1 stroke:#dc2626,stroke-dasharray:5
class A,B,C primary
flowchart LR
A([Push]):::neutral --> B[Lint]:::primary
B --> C[Test]:::primary
C --> D{Pass?}:::neutral
D -->|Yes| E[Build]:::primary
D -->|No| F[Notify]:::danger
E --> G[Deploy Staging]:::warning
G --> H{Approve?}:::neutral
H -->|Yes| I[Deploy Prod]:::success
H -->|No| J[Rollback]:::danger
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef warning fill:#fef3c7,stroke:#d97706,color:#000
classDef danger fill:#fee2e2,stroke:#dc2626,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
flowchart TD
subgraph presentation["Presentation Layer"]
direction LR
A[Web UI]:::primary
B[Mobile App]:::primary
C[CLI]:::primary
end
subgraph application["Application Layer"]
direction LR
D[Auth Service]:::secondary
E[User Service]:::secondary
F[Order Service]:::secondary
end
subgraph data["Data Layer"]
direction LR
G[(PostgreSQL)]:::neutral
H[(Redis Cache)]:::neutral
I[(S3 Storage)]:::neutral
end
A & B & C --> D & E & F
D --> G
E --> G & H
F --> G & I
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
style presentation fill:#eff6ff,stroke:#93c5fd,color:#000
style application fill:#f5f3ff,stroke:#c4b5fd,color:#000
style data fill:#f9fafb,stroke:#d1d5db,color:#000
C4 diagrams model software architecture at multiple zoom levels — from system context down to individual components. C4 uses a unique function-call syntax that differs from other Mermaid diagram types.
Keywords: C4Context, C4Container, C4Component, C4Dynamic, C4Deployment
Compatibility note: C4 requires Mermaid 10.6+. Verify your rendering platform supports it.
| Level | Keyword | Scope | Shows |
|-------|---------|-------|-------|
| Context | C4Context | Entire system | People, systems, external dependencies |
| Container | C4Container | Single system | Applications, databases, services within one system |
| Component | C4Component | Single container | Internal components of one application |
| Dynamic | C4Dynamic | Interaction flow | Numbered sequence of interactions |
| Deployment | C4Deployment | Infrastructure | Where containers run (servers, cloud, VMs) |
Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")
Person — Internal userPerson_Ext — External userSystem(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")
System_Boundary(alias, "Label") { ... }
System — System under designSystem_Ext — External systemSystem_Boundary — Groups elements belonging to one systemContainer(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
Container_Boundary(alias, "Label") { ... }
Container — Application/serviceContainerDb — DatabaseContainerQueue — Message queueContainer_Ext — External containerContainer_Boundary — Groups containersComponent(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")
ComponentQueue(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
Deployment_Node(alias, "Label", "Technology") { ... }
Node(alias, "Label", "Technology") { ... }
Rel(from, to, "Label")
Rel(from, to, "Label", "Technology/Protocol")
Rel_D(from, to, "Label") %% Downward
Rel_U(from, to, "Label") %% Upward
Rel_L(from, to, "Label") %% Left
Rel_R(from, to, "Label") %% Right
Rel_Back(from, to, "Label") %% Reverse direction
BiRel(from, to, "Label") %% Bidirectional
UpdateElementStyle(alias, $bgColor="color", $fontColor="color", $borderColor="color")
UpdateRelStyle(from, to, $textColor="color", $lineColor="color", $offsetX="n", $offsetY="n")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
Always include a title for context:
title System Context Diagram for My Application
C4Context
title System Context — SaaS Platform
Person(customer, "Customer", "Uses the web application to manage their account and resources")
Person(admin, "Admin", "Manages platform settings, users, and billing")
Person_Ext(developer, "Developer", "Integrates via API")
System(platform, "SaaS Platform", "Core platform providing resource management and analytics")
System_Ext(email, "Email Service", "SendGrid — transactional and marketing emails")
System_Ext(payment, "Payment Gateway", "Stripe — subscription billing and payments")
System_Ext(monitoring, "Monitoring", "Datadog — metrics, logs, and alerting")
System_Ext(cdn, "CDN", "CloudFront — static asset delivery")
Rel(customer, platform, "Uses", "HTTPS")
Rel(admin, platform, "Manages", "HTTPS")
Rel(developer, platform, "Integrates", "REST API")
Rel(platform, email, "Sends emails", "SMTP/API")
Rel(platform, payment, "Processes payments", "API")
Rel(platform, monitoring, "Sends telemetry", "Agent")
Rel(platform, cdn, "Serves assets", "HTTPS")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
C4Container
title Container Diagram — SaaS Platform
Person(customer, "Customer", "End user")
Person(developer, "Developer", "API consumer")
System_Boundary(platform, "SaaS Platform") {
Container(spa, "Web App", "React, TypeScript", "Single-page application for customers")
Container(api, "API Server", "Node.js, Express", "REST API handling all business logic")
Container(worker, "Background Worker", "Node.js, Bull", "Async job processing")
ContainerDb(db, "Database", "PostgreSQL", "Stores users, resources, billing")
ContainerDb(cache, "Cache", "Redis", "Session store, rate limiting, job queue")
ContainerQueue(queue, "Message Queue", "Redis/Bull", "Job queue for async processing")
Container(scheduler, "Task Scheduler", "Node.js, cron", "Periodic maintenance tasks")
}
System_Ext(email, "Email Service", "SendGrid")
System_Ext(payment, "Payment Gateway", "Stripe")
System_Ext(storage, "Object Storage", "S3")
Rel(customer, spa, "Uses", "HTTPS")
Rel(developer, api, "Calls", "REST/HTTPS")
Rel(spa, api, "Calls", "HTTPS/JSON")
Rel(api, db, "Reads/writes", "SQL")
Rel(api, cache, "Reads/writes", "Redis protocol")
Rel(api, queue, "Enqueues jobs", "Redis protocol")
Rel(worker, queue, "Processes jobs", "Redis protocol")
Rel(worker, db, "Reads/writes", "SQL")
Rel(worker, email, "Sends", "API")
Rel(worker, storage, "Uploads", "S3 API")
Rel(api, payment, "Charges", "API")
Rel(scheduler, db, "Queries", "SQL")
Rel(scheduler, queue, "Enqueues", "Redis protocol")
UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")
C4Component
title Component Diagram — API Server
Container_Boundary(api, "API Server") {
Component(router, "Router", "Express Router", "Routes HTTP requests to controllers")
Component(auth, "Auth Middleware", "Passport.js", "JWT validation and session management")
Component(controllers, "Controllers", "Express", "Request handling and response formatting")
Component(services, "Service Layer", "TypeScript", "Business logic and orchestration")
Component(repos, "Repositories", "TypeORM", "Data access and query building")
Component(validators, "Validators", "Zod", "Request payload validation")
Component(events, "Event Emitter", "EventEmitter2", "Domain event publishing")
}
ContainerDb(db, "Database", "PostgreSQL")
ContainerDb(cache, "Cache", "Redis")
ContainerQueue(queue, "Job Queue", "Bull/Redis")
Rel(router, auth, "Authenticates via")
Rel(router, controllers, "Delegates to")
Rel(controllers, validators, "Validates with")
Rel(controllers, services, "Calls")
Rel(services, repos, "Queries via")
Rel(services, events, "Publishes to")
Rel(repos, db, "Reads/writes")
Rel(services, cache, "Caches in")
Rel(events, queue, "Enqueues to")
C4Dynamic
title User Login Flow
ContainerDb(db, "Database", "PostgreSQL")
ContainerDb(cache, "Cache", "Redis")
Container(api, "API Server", "Node.js")
Container(spa, "Web App", "React")
Rel(spa, api, "1. POST /auth/login", "HTTPS")
Rel(api, db, "2. Validate credentials", "SQL")
Rel(api, api, "3. Generate JWT")
Rel(api, cache, "4. Store session", "Redis")
Rel(api, spa, "5. Return token", "HTTPS")
development
Systematic, hypothesis-driven debugging workflow with triage-based track routing. Use when asked to "fix this bug", "debug this", "why is this failing", "this is broken", "investigate this error", "track down this issue", or any debugging situation. Supports --deep flag to force full investigation.
development
Executes diagnostic investigation tasks to test debugging hypotheses. Runs tests, traces execution, checks git history, and reports evidence. (converted from agent)
content-media
Provides architectural pattern knowledge for designing feature implementations including MVC, event-driven, microservices, and CQRS patterns. Use when designing system architecture or choosing implementation patterns.
documentation
Provides Mermaid diagram syntax, best practices, and styling rules for technical visualizations. Use when creating diagrams, flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, architecture diagrams, C4 diagrams, or any visual documentation in markdown.