AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

diagramming-code

Generates Mermaid diagrams from Trailmark code graphs. Produces call graphs, class hierarchies, module dependency maps, containment diagrams, complexity heatmaps, and attack surface data flow visualizations. Use when visualizing code architecture, drawing call graphs, generating class diagrams, creating dependency maps, producing complexity heatmaps, or visualizing data flow and attack surface paths as Mermaid diagrams.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--diagramming-code at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

references/mermaid-syntax.md

Mermaid Syntax Reference

Pitfalls and edge cases when generating Mermaid from code graph data.

Contents


Node ID Sanitization

Trailmark node IDs use module:Class.method format. Mermaid node IDs only allow [a-zA-Z0-9_].

Rules applied by diagram.py:

  • Replace any non-alphanumeric character (except _) with _
  • Prefix with n_ if the result starts with a digit

Examples:

| Trailmark ID | Mermaid ID | |---|---| | query.api:QueryEngine.callers_of | query_api_QueryEngine_callers_of | | 3rdparty:init | n_3rdparty_init |


Label Escaping

Node labels are wrapped in double quotes to safely include special characters:

    node_id["label with (parens) and: colons"]

If the label itself contains double quotes, replace " with #quot; (Mermaid's HTML entity escape).


Style Definitions

Use classDef to define reusable styles and ::: to apply them:

flowchart TB
    A["Low complexity"]:::low
    B["High complexity"]:::high
    classDef low fill:rgba(40,167,69,0.2),stroke:#28a745,color:#28a745
    classDef high fill:rgba(220,53,69,0.2),stroke:#dc3545,color:#dc3545

The script defines three classes for complexity heatmaps:

  • low (green): CC < 5
  • medium (yellow): CC 5-10
  • high (red): CC > 10

And one for data flow:

  • entrypoint (blue): marks untrusted input sources

Edge Confidence Styling

Arrow syntax varies by edge confidence:

| Confidence | Arrow | Meaning | |---|---|---| | certain | --> | Direct call or self.method() | | inferred | -.-> | Attribute access on non-self object | | uncertain | ..-> | Dynamic dispatch, reflection |

For class diagrams, arrows are different:

  • <\|-- = inherits
  • <\|.. = implements

Common Pitfalls

Reserved words as node IDs: end, graph, subgraph, style, classDef, click are reserved. The sanitization function avoids most conflicts since it replaces special characters, but single-word function names matching reserved words can still collide. Workaround: use the full qualified ID which includes the module prefix.

Leading digits: Mermaid node IDs cannot start with a digit. The script prefixes n_ in this case.

Diagram size: Mermaid renderers struggle with >100 nodes. The script warns when this limit is exceeded and suggests using --focus to scope the diagram.

Empty diagrams: When no edges of the required type exist (e.g., no inherits edges in a Go codebase), the script emits a single-node diagram with an explanatory message rather than failing.

Parentheses in labels: Mermaid interprets () as rounded-rectangle node shape. Always use quoted labels (["label"]) to avoid accidental shape changes.