nordz0r/skills / plugins/all-skills/skills/pr-lens-diagrams
pr-lens-diagrams
VerifiedAnimated architecture and data-flow diagrams with PR Lens (@coldtea/pr-lens-cli): hand-write graph.json, validate it, render an animated SVG and record a seamless GIF/MP4 for chats (Telegram). Use when asked to draw a diagram, схему, архитектуру, связи сервисов или ботов, sequence/data-flow, animated diagram. Triggers: pr lens, prlens, диаграмма, схема, нарисуй, architecture diagram, data flow, animated svg, gif.
PR Lens diagrams
Russian version: references/README.ru.md.
PR Lens (MIT, https://prlens.dev) renders a JSON graph document into a self-contained animated SVG (SMIL <animateMotion>, no scripts). A model key is only needed for analyze (graph from a git diff); for an arbitrary diagram the agent writes the JSON itself.
Quick start
# deps: Node >= 20.11, npm, ffmpeg; Chromium is installed by the setup script
bash scripts/pr-lens-setup.sh # into $PR_LENS_HOME (default ~/.cache/pr-lens-diagrams)
bash scripts/pr-lens-build.sh my.graph.json out/ # → out/architecture.{svg,gif,mp4}, out/data-flow.{svg,gif,mp4}
- Start from
examples/bots.graph.json(4 lanes, 12 nodes, 12 edges, 1 flow). - The build validates, renders (
darkby default;lightorbothas the 3rd arg), records frames with Playwright atdeviceScaleFactor: 2, and encodes a non-dithered GIF and an MP4 (crf 18). - Env:
PR_LENS_HOME,FPS(20),MIN_WIDTH(1600),PR_LENS_CLI_VERSION,PLAYWRIGHT_VERSION. npx skills add coldteadotai/pr-lenscrashes on Node 20 (fs/promiseshas noglob); not required. Version-matched docs:npx pr-lens skill/npx pr-lens skill referencesinside$PR_LENS_HOME.- Never publish without explicit user consent:
pr-lens canvas pushputs the diagram on prlens.dev behind a view link anyone holding it can open.
Document (schemaVersion 0.2.0)
Required: schemaVersion, kind: "graph", title, lenses, provenance, lanes, nodes; plus edges, flows.
provenanceis required even without a repo (dummy owner/name, 40-zero sha).lanesare columns, left to right byorder; there is no "top" — the leftmost lane is the start.- Node kinds:
service|app|module|function|route|job|queue|datastore|cache|external|ui|config|test|package|other. Edge kinds:call|http|rpc|event|queue|data|dependency|render|other;emphasis: normal|hero|muted;animated: true. - Use
delta: "unchanged"everywhere for a plain diagram. layout: { direction, laneOrder, rank }are hints, never coordinates.
How the animation works
- Architecture:
animatededges carry a dot (1.6 s).heroedges carry a 3-dot train (2.1 s, 0.7 s spacing) plus glow. Seamless loop = LCM(1.6, 0.7) = 11.2 s. - Data-flow: add
"data-flow"tolensesandflows[](participants = node ids; messagessync|async|return|self). Steps light up in array order; loop length =durin the SVG (7 steps → 9.8 s, max 16 s). walkthroughandpayloadonly play on a prlens.dev canvas.- Rasterizers (resvg, cairosvg, rsvg) ignore SMIL; capture in a browser with
pauseAnimations()+setCurrentTime(t)(scripts/record.mjs).
Beauty and quality lessons
- ≤ 10–12 nodes, ~12 edges. Merge similar things into group nodes; list members in
subtitle. Express "everyone → X" in X's subtitle or via one aggregate node. - 3–4 lanes, flow left → right (input → orchestrator → workers → output), no empty or overloaded lanes.
- One card per row: same-rank nodes in a lane are seated side by side, narrow and truncated. Give each node in a lane its own
layout.rank. Rank is a floor (≥ predecessor + 1), so use a staircase 0,1,2,3…; rows are shared across lanes, so give linked neighbours the same rank for straight edges. - Short labels: subtitle ~20 chars on a narrow card, ~45 on a wide one.
heroonly for 1–2 key paths; rare edgesmuted; no labels on obvious edges.- Data-flow width ≈ 320 px per participant; keep ≤ 6–7 participants.
- Theme choice: 3rd arg
dark(default, reads best in chats),light, orboth(writes<lens>-dark.*and<lens>-light.*). Pickbothwhen the target page switches themes (GitHub<picture>, nopaste, docs sites); match the reader's theme when only one image fits. - Palette:
PALETTE=github(default renderer colours, dark ground#0d1117, light#ffffff) orPALETTE=nopaste(paste.goldfinches.ru colours: dark#212427/accent#8ab4f8, light#e6ddd2/accent#176b62). Diff colours (added/modified/removed) are never changed. - Record at DPR 2, CSS width ≥ viewBox width and ≥ 1600 px, 20 fps.
- GIF:
palettegen=max_colors=128:stats_mode=diff+paletteuse=dither=none:diff_mode=rectangle, lanczos to CSS width (~1 MB for 11 s). MP4 at full 2x. - Telegram and most chats don't animate SVG — send GIF/MP4. GitHub PR comments do show animated SVG.
- Before delivery, crop a GIF frame at 1:1 and look at it; downscaled previews hide blur.
renderoutput names carry a hash; the build copies them to stable<lens>.svg.
Agent workflow
- List the entities and group them down to 10–12 nodes. Decide which 1–2 paths are the main ones (
hero). - Copy
examples/bots.graph.jsonand edit it:lanes,nodeswith alayout.rankstaircase,edges, andflowsif needed. - Run
bash scripts/pr-lens-build.sh graph.json out/. Ifvalidatenames a wrong field, fix it. - Check the frames: no truncated labels, no paired cards, no crossings. Adjust ranks and labels if needed.
- Hand the user the GIF or MP4, the
graph.jsonsource and the SVG.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |