Official agent skill

Code Graph Mermaid Diagrams

by trailofbits in trailofbits/skills

Generates Mermaid diagrams from Trailmark code graphs, including call graphs, class hierarchies, module dependency maps, complexity heatmaps and attack surface data flows.

OfficialCC-BY-SA-4.0Auto-check passedDevelopment

Install Code Graph Mermaid Diagrams

skills CLI
$ npx skills add trailofbits/skills --skill diagramming-code -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install trailofbits/skills diagramming-code --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/trailofbits/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/trailmark/skills/diagramming-code .claude/skills/diagramming-code && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
diagramming-code
GitHub stars
7.4k
Token cost
~1.7k tokens
SKILL.md length
522 words
Files
6 (incl. scripts, references, assets)
Skills in repo
79
Repo updated
First seen
Licence
CC-BY-SA-4.0

At a glance

Generates Mermaid diagrams from Trailmark code graphs, including call graphs, class hierarchies, module dependency maps, complexity heatmaps and attack surface data flows.

  • Drawing a call graph that starts from a chosen function
  • SKILL.md covers When to Use, When NOT to Use, Prerequisites and Version Gate, plus 6 more sections
  • Runs Python scripts from its folder; calls uv
  • Showing class inheritance or members as a diagram

What it does

The agent picks a diagram type and its parameters, and a bundled script, `scripts/diagram.py`, does the Mermaid syntax generation from Trailmark's parsed code graph. The types include call graphs, class hierarchies, module dependencies, containment views with class members, complexity heatmaps with color coding, and data flow from entry points to sensitive functions. Output is raw Mermaid text, which the agent wraps in a fenced code block.

Trailmark must be installed, for example with `uv tool install trailmark`, and the agent must not fall back to hand-writing Mermaid from reading source; if installation fails it reports the error. Trailmark 0.4.0 has a native `trailmark diagram` command, so the skill checks the version and command first and uses the bundled script otherwise. It is not for plain graph queries, mutation testing triage or architecture diagrams that are not derived from code.

When your agent uses it

  • Drawing a call graph that starts from a chosen function
  • Showing class inheritance or members as a diagram
  • Mapping import dependencies between modules
  • Highlighting complexity hotspots with color coding
  • Tracing data flow from entry points to sensitive functions

Example prompts

  • “Draw a call graph of everything reachable from main, two levels deep.”
  • “Generate a class hierarchy diagram for the models package.”
  • “Make a complexity heatmap of src so I can see the hotspots.”
  • “Map module import dependencies in this repo as a Mermaid diagram.”

Requirements

  • Trailmark (`uv tool install trailmark`)
  • uv

What it can do on your machine

Read from SKILL.md and the folder at commit 82fe822. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • uv

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Code Graph Mermaid Diagrams loads about 1.7k tokens when it runs, and up to ~3.7k if it reads all its reference files. Until then it costs about 110 tokens; SKILL.md has 522 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~110
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from trailofbits/skills at commit 82fe822, republished under its CC-BY-SA-4.0 licence (© trailofbits). 522 words, ~1,701 tokens.

Download SKILL.mdSave it as .claude/skills/diagramming-code/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
name
diagramming-code
description
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.

Diagramming Code

Generates Mermaid diagrams from Trailmark's code graph. A pre-made script handles Mermaid syntax generation; Claude selects the diagram type and parameters. Trailmark 0.4.0 includes a native trailmark diagram command; use it only after a version/command check, otherwise use this skill's bundled script.

When to Use

  • Visualizing call paths between functions
  • Drawing class inheritance hierarchies
  • Mapping module import dependencies
  • Showing class structure with members
  • Highlighting complexity hotspots with color coding
  • Tracing data flow from entrypoints to sensitive functions

When NOT to Use

  • Querying the graph without visualization (use the trailmark skill)
  • Mutation testing triage (use the genotoxic skill)
  • Architecture diagrams not derived from code (draw by hand)

Prerequisites

trailmark must be installed. If uv run trailmark fails, run:

bash
uv tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

DO NOT fall back to hand-writing Mermaid from source code reading. The script uses Trailmark's parsed graph for accuracy. If installation fails, report the error to the user.

Version Gate

Check whether native v0.4 diagram support exists:

bash
trailmark diagram --help 2>/dev/null || uv run trailmark diagram --help 2>/dev/null

If this succeeds, you may use trailmark diagram. If it fails, use uv run {baseDir}/scripts/diagram.py, which keeps the older skill workflow intact. Do not assume the native CLI exists on Trailmark 0.2.x.


Quick Start

bash
uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

# Trailmark 0.4.0+ equivalent after the Version Gate succeeds
uv run trailmark diagram \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

Output is raw Mermaid text. Wrap in a fenced code block:

markdown
```mermaid
flowchart TB
    ...
```

Diagram Types

├─ "Who calls what?"               → --type call-graph
├─ "Class inheritance?"             → --type class-hierarchy
├─ "Module dependencies?"           → --type module-deps
├─ "Class members and structure?"   → --type containment
├─ "Where is complexity highest?"   → --type complexity
└─ "Path from input to function?"   → --type data-flow

For detailed examples of each type, see references/diagram-types.md.


Workflow

Diagram Progress:
- [ ] Step 1: Verify trailmark is installed
- [ ] Step 2: Identify diagram type from user request
- [ ] Step 3: Determine focus node and parameters
- [ ] Step 4: Run diagram.py script (or native trailmark diagram on v0.4+)
- [ ] Step 5: Verify output is non-empty and well-formed
- [ ] Step 6: Embed diagram in response

Step 1: Run uv run trailmark analyze --language auto --summary {targetDir}. Install if it fails. Then run pre-analysis via the programmatic API:

python
from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

Pre-analysis enriches the graph with blast radius, taint propagation, and privilege boundary data used by data-flow diagrams.

If auto-detection is wrong for the target, rerun with an explicit language or comma-separated list such as python,rust.

Step 2: Match the user's request to a --type using the decision tree above.

Step 3: For call-graph and data-flow, identify the focus function. Default --depth 2. Use --direction LR for dependency flows.

Step 4: Run the script and capture stdout. If the native v0.4 CLI is available, either command is acceptable; prefer the bundled script when you need behavior consistent with this skill's references.

Step 5: Check: output starts with flowchart or classDiagram, contains at least one node. If empty or malformed, consult references/mermaid-syntax.md.

Step 6: Wrap output in ```mermaid ``` code fence.


Show full SKILL.md (160 more words)Show less

Script Reference

uv run {baseDir}/scripts/diagram.py [OPTIONS]
# or, on Trailmark 0.4.0+:
uv run trailmark diagram [OPTIONS]
ArgumentShortDefaultDescription
--target-trequiredDirectory to analyze
--language-lpythonSource language
--type-TrequiredDiagram type (see above)
--focus-fnoneCenter diagram on this node
--depth-d2BFS traversal depth
--directionTBLayout: TB (top-bottom) or LR (left-right)
--threshold10Min complexity for complexity type
Examples
bash
# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -T call-graph -f parse_file

# Class hierarchy for a Rust project
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# Module dependency map, left-to-right
uv run {baseDir}/scripts/diagram.py -t src/ -T module-deps --direction LR

# Class members
uv run {baseDir}/scripts/diagram.py -t src/ -T containment

# Complexity heatmap (threshold 5)
uv run {baseDir}/scripts/diagram.py -t src/ -T complexity --threshold 5

# Data flow from entrypoints to a specific function
uv run {baseDir}/scripts/diagram.py -t src/ -T data-flow -f execute_query

Customization

Direction: Use TB (default) for hierarchical views, LR for left-to-right flows like dependency chains.

Depth: Increase --depth to see more of the call graph. Decrease to reduce clutter. The script warns if the diagram exceeds 100 nodes.

Focus: Always use --focus for call-graph on non-trivial codebases. For data-flow, omitting focus auto-targets the top 10 complexity hotspots.

Language: Prefer --language auto for polyglot or unfamiliar repos. Use an explicit language only when you know the target is single-language or you need to exclude unrelated components.


Supporting Documentation

© trailofbits, CC-BY-SA-4.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (scripts, references, assets) in plugins/trailmark/skills/diagramming-code of trailofbits/skills.

  • SKILL.md
  • agents/openai.yaml
  • assets/trail-of-bits-mark.svg
  • references/diagram-types.md
  • references/mermaid-syntax.md
  • scripts/diagram.py

Open the folder on GitHubat commit 82fe822

Compare with similar skills

Code Graph Mermaid Diagrams next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Code Graph Mermaid Diagrams compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Code Graph Mermaid Diagrams this skilltrailofbits/skills7.4k—~1.7kAutomated safety check: PassCC-BY-SA-4.0
GitDiagram Repository Overviewahmedkhaleel2004/gitdiagram18k—~427Automated safety check: PassMIT
GitDiagram Repo Architectureahmedkhaleel2004/gitdiagram18k—~429Automated safety check: PassMIT
draw.io Architecture DiagrammingHoangNguyen0403/agent-skills-standard570—~1.3kAutomated safety check: PassMIT
Audit Flowzebbern/claude-code-guide4.6k—~4.2kAutomated safety check: PassMIT
Archify Diagramstt-a1i/archify79k—~2.9kAutomated safety check: PassMIT

Similar skills

  • GitDiagram Repository Overview

    ahmedkhaleel2004/gitdiagram

    Explains the architecture of a public GitHub repository through GitDiagram: how the code is organized, the main components with paths, and a Mermaid diagram.

    18k GitHub stars~427 tokensUpdated today
    DevelopmentAuto-check passed
  • GitDiagram Repo Architecture

    ahmedkhaleel2004/gitdiagram

    Explains how a public GitHub repository is built by fetching its GitDiagram architecture diagram, components and optional explainer video.

    18k GitHub stars~429 tokensUpdated today
    DevelopmentAuto-check passed
  • draw.io Architecture Diagramming

    HoangNguyen0403/agent-skills-standard

    Draws architecture diagrams as editable draw.io files from a JSON spec, with a fixed house style, one C4 level per diagram and evidence-tagged shapes.

    570 GitHub stars~1.3k tokensUpdated today
    DevelopmentAuto-check passed
  • Audit Flow

    zebbern/claude-code-guide

    Interactive system flow tracing across CODE, API, AUTH, DATA, NETWORK layers with SQLite persistence and Mermaid export.

    4.6k GitHub stars~4.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Archify Diagrams

    tt-a1i/archify

    Creates interactive architecture, workflow, sequence, data-flow and lifecycle diagrams as standalone HTML with inline SVG, themes and image or video export.

    79k GitHub stars~2.9k tokensUpdated today
    DevelopmentAuto-check passed
  • Senior Architect Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin…

    259 GitHub starsUsed in 7 repos~1.2k tokens
    DevelopmentAuto-check: notes

More from trailofbits/skills

All 79 skills in this repo
  • CodeQL Security Scan

    trailofbits/skills

    Official

    Scans a codebase for vulnerabilities with CodeQL's data flow and taint tracking in run-all or important-only modes, including data extensions for project-specific sources and sinks.

    7.4k GitHub stars~4.6k tokensUpdated 5 days ago
    Auto-check: notes
  • Trailmark Graph Evolution

    trailofbits/skills

    Official

    Compares Trailmark code graphs at two snapshots, such as commits, tags or directories, to surface attack paths, blast radius and taint changes that text diffs miss.

    7.4k GitHub stars~3.4k tokensUpdated 5 days ago
    Auto-check passed
  • Let Fate Decide

    trailofbits/skills

    Official

    Draws a 12 Houses tarot spread to break ties when a request is vague or casually delegated, then reads the cards to pick the next step.

    7.4k GitHub stars~2.5k tokensUpdated 5 days ago
    Auto-check: notes
  • Semgrep Security Scan

    trailofbits/skills

    Official

    Detects languages, proposes rulesets for approval, then runs the approved Semgrep scan across a codebase and merges the output into one SARIF file.

    7.4k GitHub stars~3.7k tokensUpdated 5 days ago
    Auto-check: notes
  • Burp Suite Project Parser

    trailofbits/skills

    Official

    Searches and extracts data from Burp Suite project files on the command line: regex searches over responses, audit findings, proxy history and site map data.

    7.4k GitHub starsUsed in 3 repos~4.2k tokens
    Auto-check: notes
  • Code Context Slicing

    trailofbits/skills

    Official

    Picks a small, graph-based slice of source with Trailmark and hands a focused code task to a smaller or local model without exposing the whole repository.

    7.4k GitHub stars~2.1k tokensUpdated 5 days ago
    Auto-check passed

Works with

Questions about Code Graph Mermaid Diagrams

What does Code Graph Mermaid Diagrams do?

Generates Mermaid diagrams from Trailmark code graphs, including call graphs, class hierarchies, module dependency maps, complexity heatmaps and attack surface data flows. py`, does the Mermaid syntax generation from Trailmark's parsed code graph. The types include call graphs, class hierarchies, module dependencies, containment views with class members, complexity heatmaps with color coding, and data flow from entry points to sensitive functions.

When should I use Code Graph Mermaid Diagrams?

Code Graph Mermaid Diagrams fits situations like: drawing a call graph that starts from a chosen function; showing class inheritance or members as a diagram; mapping import dependencies between modules; highlighting complexity hotspots with color coding.

How do I install Code Graph Mermaid Diagrams in Claude Code?

Run `npx skills add trailofbits/skills --skill diagramming-code -a claude-code`. Or copy the skill folder (plugins/trailmark/skills/diagramming-code in trailofbits/skills) into .claude/skills/diagramming-code in your project. Claude Code loads it when a task matches its description.

How do I install Code Graph Mermaid Diagrams in Codex?

Run `npx skills add trailofbits/skills --skill diagramming-code -a codex`. Or copy the skill folder (plugins/trailmark/skills/diagramming-code in trailofbits/skills) into .agents/skills/diagramming-code in your project. Codex loads it when a task matches its description.

Can I use Code Graph Mermaid Diagrams in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add trailofbits/skills --skill diagramming-code -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/diagramming-code, .gemini/skills/diagramming-code, .github/skills/diagramming-code and .opencode/skills/diagramming-code in your project.

What does Code Graph Mermaid Diagrams need to run?

Going by SKILL.md and its folder, Code Graph Mermaid Diagrams needs Python for the scripts in its folder and the command-line tools its instructions call (uv). Our summary lists: Trailmark (`uv tool install trailmark`); uv.

Does Code Graph Mermaid Diagrams access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Code Graph Mermaid Diagrams safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Code Graph Mermaid Diagrams use?

Code Graph Mermaid Diagrams is published under the CC-BY-SA-4.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Code Graph Mermaid Diagrams use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2k tokens, read only when the agent opens those files.

What are the alternatives to Code Graph Mermaid Diagrams?

Skills that share tags, products or a category with Code Graph Mermaid Diagrams: GitDiagram Repository Overview (ahmedkhaleel2004/gitdiagram, 18k stars), GitDiagram Repo Architecture (ahmedkhaleel2004/gitdiagram, 18k stars), draw.io Architecture Diagramming (HoangNguyen0403/agent-skills-standard, 570 stars) and Audit Flow (zebbern/claude-code-guide, 4.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Code Graph Mermaid Diagrams?

trailofbits (a GitHub organization, an official publisher) maintains it in trailofbits/skills, which has 7,400 GitHub stars. The repository holds 79 skills in this directory. The repository was last updated on October 2, 2026.

Source: trailofbits/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.