diagramming-code skill
✓ OfficialscriptsGenerates Mermaid diagrams from code graphs to visualize call paths, class hierarchies, module dependencies, and data flows.
- GitHub stars
- 8,136
- Files
- 7
- Last commit
- Nov 11, 2026
- License
- CC-BY-SA-4.0
- Allowed tools
- —
What does the diagramming-code skill do?
diagramming-code generates Mermaid diagrams from code graphs to visualize call paths, class hierarchies, module dependencies, and data flows.
Summary generated from the skill's SKILL.md.
About the diagramming-code skill
Visualizing software architecture through Mermaid diagrams is what this skill enables for developers working with Trailmark code graphs. It transforms parsed code data into visual representations such as call graphs, class hierarchies, module dependency maps, and data flow paths. By using this tool, an agent can provide clear structural insights into a codebase without the need to manually write Mermaid syntax from source code.
An agent should load this skill when a user needs to see how functions interact, how classes inherit from one another, or where complexity hotspots exist within a directory. The process relies on the trailmark tool being installed on the system. The skill first performs a version check to determine if it should use the native trailmark diagram command available in version 0.4.0 or fall back to a bundled diagram.py script. The final output is raw Mermaid text that can be rendered in a markdown code block.
What an agent can do with it
- 1Visualize function call pathsGenerate a call graph to see which functions are calling a specific target function.
- 2Map module dependenciesCreate a left-to-right dependency map to understand how different modules import one another.
- 3Identify complexity hotspotsProduce a complexity heatmap to highlight areas of the code with high complexity using color coding.
- 4Trace sensitive data flowsTrace the path of data from entrypoints to specific sensitive functions within the application.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the diagramming-code skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the diagramming-code skill in Plugin
/plugin marketplace add trailofbits/skills /plugin install trailmark@trailofbits
Install the diagramming-code skill in Claude Code
~/.claude/skills/diagramming-code/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code ~/.claude/skills/diagramming-codeInstall the diagramming-code skill in Claude Code (project)
.claude/skills/diagramming-code/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code .claude/skills/diagramming-codeInstall the diagramming-code skill in Codex
~/.agents/skills/diagramming-code/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code ~/.agents/skills/diagramming-codeInstall the diagramming-code skill in Gemini CLI
~/.gemini/skills/diagramming-code/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code ~/.gemini/skills/diagramming-codeInstall the diagramming-code skill in Claude.ai
npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code diagramming-code && zip -r diagramming-code.zip diagramming-code # claude.ai → Customize → Skills → + → Create skill → Upload a skill → diagramming-code.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrailofbits/skills/plugins/trailmark/skills/diagramming-code is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/trailmark/sk ↗Pass
- Open source license (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Finding
- Commit or release in the last yearLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Pass
- No download-and-run or credential theft in scripts2 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 206 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Pass
SKILL.md
View on GitHubDiagramming 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
trailmarkskill) - Mutation testing triage (use the
genotoxicskill) - Architecture diagrams not derived from code (draw by hand)
Prerequisites
trailmark must be installed. If uv run trailmark fails, run:
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:
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
uv run {baseDir}/scripts/diagram.py \
--target {targetDir} --language auto --type call-graph \
--focus <function> --depth 2
# Trailmark 0.4.0+ equivalent after the Version Gate succeeds
uv run trailmark diagram \
--target {targetDir} --language auto --type call-graph \
--focus <function> --depth 2
Output is raw Mermaid text. Wrap in a fenced code block:
```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. Do not run engine.preanalysis() for a diagram: the diagram
command builds its own graph and does not use pre-analysis data, so every
diagram type is identical with or without it. data-flow uses the
entrypoints Trailmark records while parsing.
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.
Script Reference
uv run {baseDir}/scripts/diagram.py [OPTIONS]
# or, on Trailmark 0.4.0+:
uv run trailmark diagram [OPTIONS]
| Argument | Short | Default | Description |
|---|---|---|---|
--target |
-t |
required | Directory to analyze |
--language |
-l |
python |
Source language |
--type |
-T |
required | Diagram type (see above) |
--focus |
-f |
none | Center diagram on this node |
--depth |
-d |
2 |
BFS traversal depth |
--direction |
TB |
Layout: TB (top-bottom) or LR (left-right) |
|
--threshold |
10 |
Min complexity for complexity type |
Examples
# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -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/ -l auto -T module-deps --direction LR
# Class members
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T containment
# Complexity heatmap (threshold 5)
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T complexity --threshold 5
# Data flow from entrypoints to a specific function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -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
- references/diagram-types.md - Detailed docs and Mermaid examples for each diagram type
- references/mermaid-syntax.md - ID sanitization, escaping, style definitions, and common pitfalls
Files in this skill
7diagramming-code skill questions
How do I install the diagramming-code skill in Claude Code?
Run npx degit trailofbits/skills/plugins/trailmark/skills/diagramming-code ~/.claude/skills/diagramming-code. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the diagramming-code skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What types of diagrams can be generated?
The skill can produce call graphs, class hierarchies, module dependency maps, containment diagrams, complexity heatmaps, and data flow visualizations.
Should I hand-write Mermaid syntax if the script fails?
No, you should not fall back to hand-writing Mermaid from source code reading; the script uses Trailmark's parsed graph to ensure accuracy.