Skip to content

nordz0r/skills / plugins/all-skills/skills/pr-lens-diagrams

pr-lens-diagrams

Verified

Animated 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 (dark by default; light or both as the 3rd arg), records frames with Playwright at deviceScaleFactor: 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-lens crashes on Node 20 (fs/promises has no glob); not required. Version-matched docs: npx pr-lens skill / npx pr-lens skill references inside $PR_LENS_HOME.
  • Never publish without explicit user consent: pr-lens canvas push puts 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.

  • provenance is required even without a repo (dummy owner/name, 40-zero sha).
  • lanes are columns, left to right by order; 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

  1. Architecture: animated edges carry a dot (1.6 s). hero edges carry a 3-dot train (2.1 s, 0.7 s spacing) plus glow. Seamless loop = LCM(1.6, 0.7) = 11.2 s.
  2. Data-flow: add "data-flow" to lenses and flows[] (participants = node ids; messages sync|async|return|self). Steps light up in array order; loop length = dur in the SVG (7 steps → 9.8 s, max 16 s).
  3. walkthrough and payload only play on a prlens.dev canvas.
  4. 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.
  • hero only for 1–2 key paths; rare edges muted; 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, or both (writes <lens>-dark.* and <lens>-light.*). Pick both when 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) or PALETTE=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.
  • render output names carry a hash; the build copies them to stable <lens>.svg.

Agent workflow

  1. List the entities and group them down to 10–12 nodes. Decide which 1–2 paths are the main ones (hero).
  2. Copy examples/bots.graph.json and edit it: lanes, nodes with a layout.rank staircase, edges, and flows if needed.
  3. Run bash scripts/pr-lens-build.sh graph.json out/. If validate names a wrong field, fix it.
  4. Check the frames: no truncated labels, no paired cards, no crossings. Adjust ranks and labels if needed.
  5. Hand the user the GIF or MP4, the graph.json source and the SVG.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall