diagramming-code

An agent skill by trailofbits, from trailofbits/skills. Tags: analysis, architecture, diagramming, documentation.

What it does

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.

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add trailofbits/skills --skill diagramming-code

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/trailofbits/skills
cp -r skills/plugins/trailmark/skills/diagramming-code ~/.claude/skills/diagramming-code

Safety box score

Grade B, low risk: 21 of 100 risk points, rated 2026-10-21. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This skill is a read-only code-graph visualizer: it runs Trailmark on a chosen target tree and emits Mermaid diagrams. The main risks are that it executes an external Python dependency and may install that dependency from the network if missing; it does not appear to modify project files or touch secrets.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	1 (low)	It runs `uv run {baseDir}/scripts/diagram.py` or `uv run trailmark diagram`, but `scripts/diagram.py` is only a thin wrapper around `from trailmark.diagram import main`.
Network access	2 (moderate)	If Trailmark is absent, the skill explicitly says to run `uv tool install trailmark`, which can download packages from the network.
Filesystem reach	1 (low)	The skill reads the user-supplied `--target` tree to build graphs, but the shipped files only print Mermaid to stdout and do not write or delete project files.
Secrets & credentials	0 (none)	There is no prompt to read tokens, keychains, `.env` files, browser sessions, or other credential stores.
Privilege & persistence	0 (none)	It does not request sudo, register services, change shell settings, or install system-wide software.
Instruction hijack surface	0 (none)	The files do not tell the agent to ignore safeguards, follow remote instructions, or hide behavior; they only describe diagram-generation workflow.
Irreversible actions	0 (none)	It generates diagrams for the user and does not post, deploy, pay, merge, or delete anything.
Transparency	2 (moderate)	The real analysis engine is external to the repo: `scripts/diagram.py` imports `trailmark.diagram.main`, and the skill depends on an unpinned `trailmark` package (`dependencies = ["trailmark"]`, `uv tool install trailmark`).

Before installing

Check whether you trust the external `trailmark` package source, since the skill may install it with `uv tool install trailmark`.
Review `scripts/diagram.py` to confirm it is only a wrapper around `trailmark.diagram.main`.
Run it once against a scratch repository and verify it only reads the target tree and prints Mermaid to stdout.
If reproducibility matters, pin the Trailmark version before relying on generated diagrams.

Rated 2026-10-21 by an automated review of 7 files from the skill's repository.

Source

Repository: trailofbits/skills (all skills from this repository)
Path: plugins/trailmark/skills/diagramming-code/SKILL.md
Branch: main
Collection: trailmark
Updated: 2026-09-19

trailmark-summary — Runs a Trailmark summary analysis on a codebase. Returns auto-detected languages, entry point count, and dependency list.
how — Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live".
domain-modeling — Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
crypto-protocol-diagram — Extracts protocol message flow from source code, RFCs, academic papers, pseudocode, informal prose, ProVerif (.pv).
trailmark — Builds and queries multi-language source and binary code graphs for security analysis.
trailmark-structural — Runs full Trailmark structural analysis by building a graph, running `preanalysis()`, and reporting hotspots, taint, blast radius, privilege boundaries.