Skip to content
Back to skills

Excalidraw Pr Diagrams

ASecurity

Draw Excalidraw diagrams that make a visual argument, such as a pull request's before/after visual overview, an architecture, a workflow or a shareable explainer, then render them to PNG and check them by eye.

  • 9 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 10, 2026
ai-agentsrustgobashnodegitapi

Works with

  • cli
  • api

Security analysis

A100/100

Pro scans all 8 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add greenfield-inc/agent-farm --skill excalidraw-pr-diagrams --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Excalidraw Pr Diagrams?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Excalidraw Pr Diagrams
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/greenfield-inc-excalidraw-pr-diagrams-b0cd924e/badge)](https://www.skillsdirectory.com/skills/greenfield-inc-excalidraw-pr-diagrams-b0cd924e)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: excalidraw-pr-diagrams
description: Draw Excalidraw diagrams that make a visual argument, such as a pull request's before/after visual overview, an architecture, a workflow or a shareable explainer, then render them to PNG and check them by eye.
---

# Excalidraw PR diagrams

A diagram argues; it doesn't display. Its shape should carry the meaning, so a reader can explain the change by pointing at it.

## Workflow

1. **Find the visual truth.** Before drawing, name what the change does, and pick the structure that shows it:

   | The change... | Draw |
   |---|---|
   | moves a boundary | walls, trust zones, process or origin boundaries |
   | changes a lifecycle | a state machine, gate sequence or retry loop |
   | moves responsibility | before/after ownership regions, with the action crossing them |
   | removes a failure mode | the old path dead-ending, the new path avoiding it |
   | fixes a race | timelines, clocks or joins |
   | changes validation or permissions | a decision path with the gate and what passes |
   | fans out, converges, or transforms | radial arrows, a funnel, or input → process → output |

   Give each major concept its own pattern. Two PRs that fix different kinds of problems get different layouts.
2. **Gather the real details.** Use the actual endpoint paths, event names, fields and example payloads from the code or spec. Concrete artifacts teach: a dark code box with the real query or command, a mock of the real menu or dialog built from nested rectangles, or bars on a time axis for states over time. Tag the pieces the PR adds or changes with small `NEW`, `CHANGED` or `REUSED` badges, and say once what each badge means.
3. **Write the file** in a working folder outside the repository, such as `/tmp/pr-diagrams/<repo>-<pr>/overview.excalidraw`, using the format below. Build a large diagram one region per edit, or generate repeated pieces (timeline rows, badges) with a short script. For a PR whose diff is mostly generated files, list it with `gh pr diff --name-only` and read only the files that matter.
4. **Render and look** (below), fix what you see, and repeat until the checks at the end pass, usually 2–4 rounds.

A PR visual overview always has:
- **one skeleton, drawn twice:** Before above After, with the same structure (the same columns, lanes, rows or time axis) in the same positions in both, so the change is the one part that differs and a reader finds it by position;
- a **Before** path, where the old system failed or was fragile. When the old system worked for one case and failed for another, show both, so the contrast locates the failure;
- an **After** path through the new route or control point, with the same cases as Before;
- one short **truth statement** in plain language;
- a small **term explainer** for any protocol word a reviewer may not know (header, preflight, origin, token, cookie, cache key…): define it in a few plain words, then keep the official term in parentheses, for example `permission check (CORS preflight)`. Show who acts: `Browser asks`, `API answers`.

For a shareable explainer, title it with the outcome rather than the implementation, put the old blind spot on the left and the new loop or control point on the right, and include one real input and one real output.

## File format

Write short element skeletons. The renderer fills in ids, seeds, bindings and text sizes, and writes the expanded file to `<name>.full.excalidraw`, which opens in excalidraw.com for editing.

```json
{"type": "excalidraw", "version": 2, "elements": [
  {"type": "text", "x": 0, "y": 0, "text": "After: the token is checked before the write", "fontSize": 32, "strokeColor": "#1e40af"},
  {"type": "rectangle", "id": "client", "x": 0, "y": 80, "width": 200, "height": 80,
   "backgroundColor": "#fed7aa", "strokeColor": "#c2410c", "label": {"text": "Browser sends\nPOST /orders", "fontSize": 20}},
  {"type": "diamond", "id": "gate", "x": 320, "y": 70, "width": 180, "height": 100,
   "backgroundColor": "#fef3c7", "strokeColor": "#b45309", "label": {"text": "token valid?", "fontSize": 20}},
  {"type": "arrow", "x": 200, "y": 120, "width": 120, "height": 0, "start": {"id": "client"}, "end": {"id": "gate"}, "label": {"text": "1", "fontSize": 20}},
  {"type": "line", "x": 0, "y": 200, "points": [[0, 0], [820, 0]], "strokeStyle": "dashed", "strokeColor": "#64748b"},
  {"type": "ellipse", "x": 0, "y": 230, "width": 14, "height": 14, "backgroundColor": "#3b82f6", "strokeColor": "#3b82f6"}
]}
```

- Types: `rectangle` (an action or component), `ellipse` (a start, an end, or a 10–20 px timeline dot), `diamond` (a decision), `arrow` (a relationship), `line` (timelines, trees, dividers), `text`.
- Bind an arrow to rectangles and ellipses with `start`/`end` ids. For a diamond, leave the arrow unbound and give its `points`, so it leaves from the edge you choose.
- With `start`/`end` set, the arrow's ends snap to the shapes; still give `x`, `y` and `points` as a starting route.
- Size text with monospace at about 0.6 × font size per character, plus 24 px of padding inside a box. A badge is a small rectangle with a 14 px label, for example `NEW` at 60 × 26.
- A label on a shape or an arrow defaults to 16 px, the detail size, and takes its stroke colour; set `label.fontSize: 20` on the skeleton's labels, and `label.strokeColor` to change the colour. Where an arrow label would cross another line, use free-floating text beside the arrow instead.
- The defaults are clean edges (`roughness: 0`), rounded rectangles, a monospace font (`fontFamily: 3`) and `strokeWidth: 2`. Set `roughness: 1` only for a sketchy look.
- Add `"strokeStyle": "dashed"` for an inactive or removed path, and `"roundness": null` for square corners.

**Colours** (fill / stroke; keep a darker stroke on a lighter fill):

| Meaning | Fill | Stroke |
|---|---|---|
| Neutral, primary | `#dbeafe` | `#1e3a5f` |
| Start, trigger | `#fed7aa` | `#c2410c` |
| Success, end | `#a7f3d0` | `#047857` |
| Decision | `#fef3c7` | `#b45309` |
| Error, failure | `#fecaca` | `#b91c1c` |
| AI, model | `#ddd6fe` | `#6d28d9` |
| Code or data box | `#1e293b` | `#1e293b`, with text in `#22c55e` or `#e2e8f0` |

Text colours: title `#1e40af`, subtitle `#3b82f6`, detail `#64748b`. Colour supports the meaning but never carries it alone.

## Layout and text

- **Draw for two reading distances:** GitHub shows a PR image about 900 px wide, and a click opens it full size. Keep the canvas at most 1600 px wide, measured in the file's own coordinates (the PNG is twice that plus 40 px), and let it grow downward, with 40 px between regions. The renderer adds the outer margin.
- **Argument text reads without a click:** the title (32 px, under about 50 characters), region headings (24–26 px), the labels of the skeleton's shapes and arrows, and the truth statement are 20 px or larger, which shows at 11 px. At most three short lines per shape, with line breaks written in; a label names the thing or the step.
- **Detail text reads after a click:** the real artifacts from step 2 (the lines in a code box, the text of a mock menu or dialog, payloads, file paths, notes) are 14–16 px, and badges 14 px. Use the room for them: put each artifact at the step where it acts. When something doesn't fit, cut words, never the font size.
- Leave most text free-floating, with font size and colour as hierarchy; box something only when it's a focal point, a "thing" in the system, or an arrow end.
- Give the most important element the most space. Every relationship gets an arrow. Arrows run horizontally or vertically; for a turn, give three points that make a right angle. Route them through the gaps, around boxes and text.

## Render and check

Render from your working folder:

```bash
node <skill-directory>/references/render.mjs /tmp/pr-diagrams/<repo>-<pr>/overview.excalidraw
```

`<skill-directory>` is this skill's folder. The PNG lands next to the file, sized to the diagram. The renderer needs only Node and a browser already on the machine (Chrome, Edge or Chromium; set `BROWSER_PATH` for another location), and loads Excalidraw from esm.sh, so it needs network access. If it can't run, put a Mermaid flowchart with the same before and after paths in the Visual Overview, and say the image wasn't rendered.

Look at the PNG with your image-reading tool (for example the Read tool), then check:
- **The argument:** without the prose, the image still shows the before/after difference through structure, and isn't just the PR text in red and green boxes.
- **The fit:** no text is clipped or overlapping, arrows land on the right element without crossing others, spacing is even, and the title doesn't dominate.
- **The size:** the widest row of the file spans at most 1600 px (a PNG at most 3240 px wide), argument text is 20 px or larger, and no text is under 14 px. If it's too wide or wordy, stack regions vertically and cut prose.

## Publishing on a PR

PR images are hosted, not committed.
1. **Reuse the repository's asset release** (`pr-assets`, then `pr-assets-2`, `pr-assets-3` and so on; list them with `gh release list`). Upload to the highest-numbered one that has room. A GitHub release holds 1,000 assets, so when the newest holds 990 or more, create the next number (`gh release create pr-assets-<N+1> --title pr-assets-<N+1> --notes "PR images"`) without asking, and say so in your report. Creating the first `pr-assets` release needs the person's explicit go-ahead, once per repository; without it, keep the PNG local and report publishing as blocked, with the exact `gh release create` and `upload` commands.
2. **Name the file by content:** `pr-<number>-<head-short-sha>-<sha256-first-12>-visual-overview.png`. Reuse an existing asset only when its digest matches. For different content, upload under a new name, so images in older PRs never change.
3. **Verify the upload:** download the asset URL and compare its SHA-256 and size with the local file.
4. **Embed it** right under the PR's summary, in a `## Visual Overview` section between `<!-- pr-visual-overview:start -->` and `<!-- pr-visual-overview:end -->`, followed by the link to the PR's own artifact (`prepare-pr`'s companion page). In a private repository, add a line under the image: "The image may not show for everyone; it and the rest of this PR's material are in <the PR's artifact>." Replace only that section on reruns.
5. **Read the PR body back** and confirm the image loads and the Markdown renders as separate sections.

Commit an image only when tracked docs need it, under `docs/` or `.github/pr-assets/`. Keep `.excalidraw` sources outside the repository unless the person asks to track them.

Files in this skill

  • README.md3.3 KB
  • SKILL.md37.2 KB
  • references/color-palette.md2.1 KB
  • references/element-templates.md4 KB
  • references/json-schema.md1.9 KB
  • references/pyproject.toml127 B
  • references/render_excalidraw.py6.6 KB
  • references/render_template.html1.7 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.