diagramming-code

Files (7)

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

SKILL.md (first lines)

# 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 <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:

````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](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

From trailofbits/skills, CC-BY-SA-4.0.

More from trailofbits/skills