Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/mermaid-diagrams

mermaid-diagrams

Verified

Author Mermaid diagrams inside ```mermaid fenced code blocks in markdown files (README, AGENTS.md, PR descriptions, chat responses). Covers every stable, non-experimental diagram type: flowchart, sequence, class, state, entity relationship, user journey, Gantt, pie, quadrant, requirement, gitGraph, block, packet, kanban, XY chart, event modeling. Use when: picking a diagram type; writing correct fence syntax; documenting architecture, processes, timelines, schemas, or data relationships compactly for humans and agents alike, since a diagram conveys structure in far fewer tokens than prose. DO NOT USE FOR: the Mermaid Live Editor or mermaid.ai chat (fence syntax only); experimental or beta diagrams (swimlanes, mindmap, timeline, sankey, architecture, radar, treemap, venn, ishikawa, wardley, cynefin, treeView, ZenUML, C4); general Markdown formatting (use markdown-best-practices).

references/structure-and-data.md

View on GitHub
# Structure and Data Diagrams

Flowchart, Class, State, Entity Relationship, and Block diagrams document what a system *is* — its logic, shape, or schema — rather than what happens over time.

## Flowchart

**When to use:** branching logic, a process, a decision tree, or any directed graph of steps.

````markdown
```mermaid
flowchart TD
    Start([Start]) --> Check{Valid input?}
    Check -->|Yes| Process[Process request]
    Check -->|No| Reject[Return error]
    Process --> End([Done])
```
````

| Syntax | Meaning |
| --- | --- |
| `flowchart TD` / `LR` / `BT` / `RL` | Direction: top-down, left-right, bottom-up, right-left |
| `id[Text]` | Rectangle (process) |
| `id(Text)` | Rounded rectangle |
| `id([Text])` | Stadium (start/end) |
| `id{Text}` | Rhombus (decision) |
| `id((Text))` | Circle |
| `A --> B` | Arrow; `A -->\|label\| B` adds a label |
| `A -.-> B` | Dotted arrow; `A ==> B` thick arrow |
| `subgraph Name ... end` | Group nodes visually |

Gotchas: the bare word `end` (all lowercase) breaks parsing — capitalize it (`End`) if used as a node label. A node id starting with `o` or `x` right before `--` can be misread as a circle/cross edge — add a space or capitalize.

## Class Diagram

**When to use:** modeling object-oriented structure — classes, attributes, methods, and how classes relate.

````markdown
```mermaid
classDiagram
    Animal <|-- Duck : inherits
    Animal : +int age
    Animal : +isMammal()
    class Duck {
        +String beakColor
        +swim()
    }
```
````

| Relation | Meaning |
| --- | --- |
| `A <\|-- B` | Inheritance (B inherits from A) |
| `A *-- B` | Composition |
| `A o-- B` | Aggregation |
| `A --> B` | Association |
| `A ..> B` | Dependency |
| `A ..\|> B` | Realization (interface implementation) |

Members use `+`/`-`/`#`/`~` for public/private/protected/package visibility; a trailing `()` marks a method vs. an attribute. Use `class Name { ... }` to group members, or `class Name` on its own line then `Name : member` per line.

## State Diagram

**When to use:** modeling the states of a single entity (order, connection, UI component) and its transitions — not multiple actors.

````markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Running : start
    Running --> Idle : stop
    Running --> Failed : error
    Failed --> [*]
```
````

`[*]` marks the start/end pseudostate. Use `state Name { ... }` for a composite (nested) state, and `<<choice>>` / `<<fork>>` / `<<join>>` for branching logic inside the diagram. Use `direction LR` (etc.) to change orientation.

## Entity Relationship Diagram

**When to use:** modeling database entities, their attributes, and cardinality of relationships — logical or physical data models.

````markdown
```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string custNumber
    }
```
````

Cardinality markers go on both ends: `|o` zero-or-one, `||` exactly one, `}o` zero-or-more, `}|` one-or-more. `--` = identifying (solid line), `..` = non-identifying (dashed line). Attribute blocks (`ENTITY { type name }`) support key annotations `PK`/`FK`/`UK` after the name.

## Block Diagram

**When to use:** a freeform architecture or system diagram where you need explicit control over node position (Mermaid's flowchart auto-layout can misplace shapes); good for network/software architecture sketches.

````markdown
```mermaid
block
columns 3
  Frontend space Backend
  space:2 down<[" "]>(down)
  Disk left<[" "]>(left) Database[("DB")]
```
````

`columns N` sets a grid width; blocks fill left-to-right, wrapping to new rows. `space` (or `space:N`) reserves empty grid cells for layout. `block:id ... end` nests a composite block. Node shapes reuse flowchart shape syntax (`[Text]`, `(Text)`, `((Text))`, `[(Text)]` for cylinder/database, etc.).
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall