Skip to content
Back to search

visualise

Agent skill for rendering inline interactive visuals — SVG diagrams, HTML widgets, charts, and explainers — in agent conversations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bentossell--visualise/badge.svg)](/listings/bentossell--visualise)

HTML

<a href="/listings/bentossell--visualise"><img src="/api/listings/bentossell--visualise/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**User-level (recommended)**

git clone https://github.com/bentossell/visualise.git ~/.agents/skills/visualise

**Project-level**

git clone https://github.com/bentossell/visualise.git .agents/skills/visualise

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 119 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: visualise
  3. description: "Render inline interactive visuals — SVG diagrams, HTML widgets, charts, and explainers — directly in the conversation. Use this skill whenever the user asks to visualize, diagram, chart, illustrate, or explain something visually, or when an explanation would genuinely benefit from a spatial/interactive diagram rather than text. Also triggers for: flowcharts, architecture diagrams, data visualizations, interactive explainers, comparison layouts, UI mockups, and any request containing 'show me', 'draw', 'map out', 'visualize', or 'diagram'. Even when the user doesn't explicitly ask for a visual, use this skill proactively when the topic has spatial, sequential, or systemic relationships that a diagram would clarify better than prose."
  4. ---
  5. # Inline Visualizer
  6. Render rich visual content — SVG diagrams, HTML interactive widgets, charts — directly inline in a chat conversation. Output streams token-by-token into a sandboxed iframe. The result feels like a natural extension of the conversation, not an attachment.
  7. ## How it works
  8. You generate raw HTML or SVG fragments. The client renders them in a sandboxed iframe with the design system's CSS variables injected. No `<html>`, `<head>`, or `<body>` tags — just content fragments.
  9. **Two output modes:**
  10. - **SVG mode**: Output starts with `<svg>`. Client auto-wraps in a card. Best for static diagrams.
  11. - **HTML mode**: Raw HTML fragment. Best for interactive content (sliders, tabs, charts, controls). You can embed `<svg>` elements inside HTML mode.
  12. The client detects which mode based on whether the output starts with `<svg`.
  13. ## Before generating any visual
  14. Read the design system reference before your first visual in a conversation:
  15. 1. **Always read first**: `references/design-system.md` — CSS variables, color ramps, typography, core rules
  16. 2. **Then read the relevant module**:
  17. - Diagrams (flowcharts, structural, illustrative): `references/diagrams.md`
  18. - Interactive explainers, comparisons, data records: `references/components.md`
  19. - Charts (Chart.js, data viz): `references/charts.md`
  20. Read the design system file once per conversation. Read module files as needed for each visual type.
  21. ## Streaming constraints
  22. Output streams token-by-token into the DOM. This dictates structure:
  23. 1. `<style>` first (keep under 15 lines — inline styles preferred)
  24. 2. Visible HTML/SVG content next (the user sees it building up)
  25. 3. `<script>` last (executes only after streaming completes)
  26. **Because of streaming:**
  27. - No gradients, drop shadows, blur, or glow — they flash during DOM diffs. Use flat fills.
  28. - No `display:none` or hidden content — it streams invisibly.
  29. - No `<!-- comments -->` or `/* comments */` — waste tokens, break streaming.
  30. - Inline `style="..."` preferred over `<style>` blocks so elements look correct mid-stream.
  31. - No tabs or carousels that start hidden — show everything stacked vertically during stream. Post-streaming JS can add interactivity.
  32. ## Iframe sandbox rules
  33. The visual renders in a sandboxed iframe. These are hard constraints:
  34. - **No localStorage / sessionStorage** — all state must be in-memory
  35. - **No position: fixed** — the iframe auto-sizes to content height; fixed elements collapse it
  36. - **No external fetches** — CSP blocks API calls from inside the widget
  37. - **CDN allowlist only**: `cdnjs.cloudflare.com`, `esm.sh`, `cdn.jsdelivr.net`, `unpkg.com`
  38. - **No DOCTYPE, `<html>`, `<head>`, `<body>`** — just content fragments
  39. - Background is transparent — the host provides the container/card styling
  40. - Load libraries via `<script src="https://cdnjs.cloudflare.com/ajax/libs/...">` (UMD globals)
  41. ## The sendPrompt bridge
  42. A global `sendPrompt(text)` function is available inside the iframe. It sends a message to the chat as if the user typed it. Use it to make visuals conversational — clicking a node in a diagram can trigger a follow-up explanation.
  43. Use `sendPrompt` when the user's next step benefits from the model thinking. Handle filtering, sorting, toggling, and calculations in local JS instead.
  44. ## Choosing the right visual type
  45. Route on the verb, not the noun. The same subject gets different treatment depending on what was asked:
  46. | User says | Type | What to build |
  47. |-----------|------|---------------|
  48. | "how does X work" | Illustrative diagram | Spatial metaphor showing the mechanism |
  49. | "what are the components of X" | Structural diagram | Labelled boxes showing containment |
  50. | "walk me through the steps" | Flowchart | Sequential boxes and arrows |
  51. | "compare X vs Y" | Comparison layout | Side-by-side cards with metrics |
  52. | "show me the data" | Chart | Chart.js or inline data viz |
  53. | "explain X" (spatial concept) | Interactive explainer | Sliders, controls, live state |
  54. Default to illustrative for "how does X work" — it's the more ambitious choice. Don't retreat to a flowchart because it feels safer.
  55. ## Multiple visuals per response
  56. Generate multiple visuals in a single response, interleaved with prose:
  57. 1. Text block (introduce/explain)
  58. 2. Visual
  59. 3. Text block (transition)
  60. 4. Visual (if needed)
  61. Never stack visuals back-to-back without text between them.
  62. ## Output wrapper
  63. Wrap visual output in a code fence with the language tag `visualizer` so the client detects and routes it to the iframe renderer:
  64. ````
  65. ```visualizer
  66. <svg width="100%" viewBox="0 0 680 400">
  67. ...
  68. </svg>
  69. ```
  70. ````
  71. The client strips the fence and injects the content into the iframe with theme variables prepended.
  72. ## Quick reference
  73. | Rule | Value |
  74. |------|-------|
  75. | SVG viewBox width | Always 680px |
  76. | Font sizes | 14px labels, 12px subtitles only |
  77. | Stroke width | 0.5px for borders and edges |
  78. | Max colors per diagram | 2-3 ramps |
  79. | Box subtitle length | ≤5 words |
  80. | Corner radius (SVG) | rx="4" default, rx="8" for emphasis |
  81. | Corner radius (HTML) | `var(--border-radius-md)` or `-lg` |
  82. | Min font size | 11px |
  83. | Text weights | 400 regular, 500 bold only |
  84. | Heading sizes | h1=22px, h2=18px, h3=16px |
README.md · README · 55 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # visualise
  2. An [Agent Skill](https://agentskills.io) that lets coding agents render rich interactive visuals — SVG diagrams, HTML widgets, charts, and explainers — directly inline in conversations.
  3. Instead of describing a flowchart or pasting ASCII art, the agent generates a real interactive visual. Diagrams you can click, sliders you can drag, charts that update live.
  4. built by [droid](http://factory.ai/)
  5. ## Installation
  6. **User-level (recommended)**
  7. ```
  8. git clone https://github.com/bentossell/visualise.git ~/.agents/skills/visualise
  9. ```
  10. **Project-level**
  11. ```
  12. git clone https://github.com/bentossell/visualise.git .agents/skills/visualise
  13. ```
  14. ## Usage
  15. The skill activates automatically when you ask an agent to:
  16. - Visualize, diagram, or chart something
  17. - Explain how something works (spatial/sequential concepts)
  18. - Compare options side-by-side
  19. - Draw, map out, or illustrate an idea
  20. Or just say: *"show me"*.
  21. ## How It Works
  22. The skill uses progressive disclosure to stay lean. At startup, only the name and description are loaded (~100 tokens). When activated, the agent reads the main instructions, then pulls in only the reference docs it needs:
  23. - **design-system.md** — CSS variables, color ramps, typography
  24. - **components.md** — interactive explainers, comparisons, cards, steppers
  25. - **diagrams.md** — flowcharts, structural, illustrative diagrams
  26. - **charts.md** — Chart.js and data viz patterns
  27. Output is raw HTML/SVG fragments rendered in a sandboxed iframe. No build step, no dependencies.
  28. ## Client support
  29. This skill teaches agents *what to generate* — it doesn't include a renderer. The output is HTML/SVG wrapped in a `visualizer` code fence.
  30. If your agent client supports rendering that fence in a sandboxed iframe, visuals appear inline. If not, the output is still valid HTML you can open in a browser.
  31. See `references/client-implementation.md` for a full guide on adding renderer support to an agent client.
  32. ## License
  33. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.