graphally

An agent skill for professional diagrams. The agent writes a diagram as a small web page: HTML for what exists and what contains what, CSS (mostly Tailwind-style utility classes) for where it goes, and a JSON list for what connects to what. graphally lays the page out in a browser, routes the connections around the boxes, places the labels, applies the theme, and writes an SVG. Nobody writes a coordinate.

It draws architecture (with Azure and AWS icons), networks, hierarchies, BPMN processes, flowcharts, sequence diagrams, Gantt plans and roadmaps, phase and role charts, figures for proposals and solution designs, and any other figure a grid can hold, and drafts diagrams of Terraform repositories from the code.

Every figure above was drawn by an agent from a brief; the showcase has each one with its brief and the source the agent wrote.

Every diagram comes in a light and a dark theme from the same source: render --themes writes both, a page shows the one that matches its reader, and a diagram opened in a browser follows the system setting.

Install

The skill is self-contained: one folder with its instructions, scripts and assets. It needs Node.js 18 or later and Chrome, Chromium or Edge on the machine where the agent runs. There is no npm install and nothing to clone. The first render downloads the Azure and AWS icon packs into the skill, which takes a few seconds once.

Claude Code

/plugin install graphally --marketplace kwilcz/graphally

On versions of Claude Code without the one-step form, run /plugin marketplace add kwilcz/graphally and then /plugin install graphally@graphally.

GitHub CLI (2.90 or later), for Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI and the other agents it supports:

gh skill install kwilcz/graphally graphally --scope user

GitHub Copilot CLI

copilot plugin marketplace add kwilcz/graphally
copilot plugin install graphally@graphally

skills CLI

npx skills add kwilcz/graphally --skill graphally -g

npm, for developers and CI without an agent: the same engine, as a command and a Node API (import { render } from 'graphally').

npx graphally render diagram.html --png

Claude.ai and Claude Desktop: download graphally-skill.zip from the latest release and upload it under Settings → Capabilities → Skills.

If no browser is found, the skill says so; npx playwright install chromium installs one, or set CHROMIUM_PATH to an existing browser. Without internet access, diagrams render without vendor icons until node skills/graphally/scripts/fetch-icons.mjs is run once online.

Use

Ask your agent for a diagram as you would ask a colleague: "draw the architecture of this service", "diagram the Terraform in ./infra", "a sequence diagram of the checkout". The agent writes the source, renders it, fixes anything reported, and looks at a preview once.

Every diagram source is also a page: open the .html file in a browser (a double-click will do) and it draws itself. The render adds a three-line header that loads graphally's viewer from jsDelivr, so a colleague without the skill can read the diagram, edit its text and reload. GitHub shows .html files as source, so the rendered .svg stays the file to embed in a README. To work offline or behind a strict firewall, commit skills/graphally/viewer/graphally.min.js next to the diagrams and point the header's src at it; graphallyOptions (see the top of viewer.js) points the icons and the typeface at a mirror.

To put diagrams in a page of your own (a site, a wiki, a report), load the viewer once and write any number of <diagram> elements where they should appear. Each one is isolated: its <style>, scripts, connections and ids belong to it alone, and your page's CSS does not reach it, so ten diagrams can each have a .card and an id=api of their own. Your page restyles them only through the theme's tokens, set on the box each is drawn in: .graphally-view { --woad: #e30613; }.

The source looks like this:

<diagram width=1000 title="Orders platform">
<div class="grid grid-cols-3 items-start justify-between gap-x-20">
  <div class=group><h4>Edge</h4>
    <div class=node id=fd><icon name="front door"></icon>Front Door<small>WAF</small></div></div>
  <div class=group><h4>Application</h4>
    <div class=node id=api><icon name="app service"></icon>Orders API<small>App Service</small></div></div>
  <div class=group><h4>Data</h4>
    <div class=node id=db><icon name=sql></icon>Orders DB<small>Azure SQL</small></div></div>
</div>
<script type="application/json">
[ ["fd", "api", "HTTPS"], ["api", "db", "writes"] ]
</script>
</diagram>

The page uses whatever CSS lays it out best: utility classes with Tailwind's names (grid grid-cols-3 gap-x-20), building blocks that look like graphally (node, group, band, key), shapes (shape="cylinder", shape="gateway exclusive"), and two helpers for what CSS cannot do, dates to grid columns and messages to rows. A short drawing script adds marks that have no box, such as a gate on a boundary. The whole format is in skills/graphally/references/format.md, with a page per kind of diagram beside it.

The skill's scripts can also be run directly:

node skills/graphally/scripts/graphally.mjs render diagram.html --png    # SVG and a preview PNG
node skills/graphally/scripts/graphally.mjs render diagram.html --png2x  # a sharp PNG to publish
node skills/graphally/scripts/graphally.mjs render diagram.html --themes  # also diagram-dark.svg, the dark theme
node skills/graphally/scripts/graphally.mjs render diagram.html --recompute  # lay out afresh, ignoring the previous SVG
node skills/graphally/scripts/graphally.mjs render a.html b.html c.html  # several files in one browser, in parallel
node skills/graphally/scripts/edit.mjs diagram.html --move db 0,20 --connect api cache "reads"  # patch moves and connections
node skills/graphally/scripts/tf2graphally.mjs ./infra --out diagram.html  # a Terraform configuration, drafted
node skills/graphally/scripts/fetch-icons.mjs                            # download or refresh the icon packs

Source and output. The .html source is the diagram; the SVG next to it is compiled output. Edit the source and render again: the render reads the previous SVG's layout, so what you did not change stays where it was. Corrections made by hand live in the source (nudge="0,24" on an element, "out": "bottom" on a connection), so they survive later edits, and a render that loses one says so. To commit the SVGs for your docs but keep them out of pull-request diffs, mark them as generated in .gitattributes:

*.svg linguist-generated=true

Colours are CSS tokens in skills/graphally/assets/theme.css, with a light and a dark set, so a brand theme only redefines them (in a page, on .graphally-view).

Samples

The showcase has every sample, in your theme, with the brief the agent was given and the source it wrote.

• Basic, the everyday technical diagrams: architecture, AWS, network, Terraform repository, BPMN process, flowchart, sequence, hierarchy, icon diagram.
• Advanced, figures that go past boxes and lines, most of them for proposals and solution designs: Gantt plan, phase and role chart, governance pyramid, scope target, solution stack.
• Designed for the point, from briefs that name no kind of diagram: why the cloud bill grew, where customer data comes from and the same brief, another design, three waves to Azure, how a change reaches production, who is responsible for what, the orders diagram, for business; and, in depth, an Azure platform, AWS telemetry ingestion, a landing zone network and a BPMN claim process.

Releases

Every pull request merged into main is a release, and its label chooses which: build (the default, also with no label), minor or major. At the merge, the release workflow works out the next version from the last tag, commits it to main, tags it and publishes the release with the skill attached; on the pull request, its summary says which version the merge will make. The version lives in SKILL.md, the three plugin manifests and the skill folder's package.json: node tools/version.mjs prints it, and --check checks that they agree. Diagrams load the viewer of their major version (…/graphally@2/…), which follows its latest release.

The skill folder is also the npm package graphally, with nothing copied: the graphally command (scripts/graphally.mjs), the Node API (import { render } from 'graphally', the same render the command runs), the browser engine (graphally/engine), source edits (graphally/edits) and the viewer (graphally/viewer). Agents keep using the skill's own copy, which works without a network. Each release stages the package on npm at the same version, through trusted publishing (no token is kept) while the repository variable NPM_PUBLISH is true; it goes live when a maintainer approves it with 2FA on npmjs.com (Staged Packages) or with npm stage approve.

Repository

Licence

graphally is licensed under the Apache License, Version 2.0: you may use, copy, modify and redistribute it, commercially included, provided you keep the copyright and licence notices (NOTICE). The diagrams you make with it are yours.

Cloud icons are not part of graphally and not covered by this licence. The skill downloads Microsoft's Azure icons from the draw.io project and the AWS Architecture Icons from the npm registry; they remain subject to Microsoft's and Amazon's terms.