Skip to content
Get packs

Guide · Agent skill

How to use the FigureSpec Architecture Diagrams agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The figure-spec skill lets an AI agent turn a description of a system, pipeline or workflow into a structured JSON spec (FigureSpec) and render it locally as an editable SVG vector diagram. It is meant for formal architecture, workflow and audit-cascade figures for papers and technical documents. After this guide you will know how to install the skill, how to ask for a diagram in plain language, and how to check and adjust the result.

FigureSpec Architecture Diagramswanshuiyin/Auto-claude-code-research-in-sleep · MIT

Quick start

  1. 1Download and unzip the skill. Download the figure-spec ZIP from this page and unzip it. Place the figure-spec folder in ~/.claude/skills/ or in your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Check the requirements. Confirm Python 3 is installed and that the agent has Bash shell access. Reviewer MCP tools are optional and not needed for basic diagrams.
  3. 3Ask for a diagram in plain language. Describe the entities, how they connect and any groups or layers. Use a trigger phrase such as architecture diagram, workflow figure or pipeline figure.
  4. 4Let the agent draft the JSON spec. The agent turns your description into a FigureSpec JSON file with canvas size, nodes, edges and groups.
  5. 5Validate and render. The agent runs the renderer's validate command, fixes any reported errors, then renders the spec to an SVG file.
  6. 6Review and iterate. Open the SVG or PDF, check for overlaps, readability and clear arrows, then ask the agent to change the spec and re-render.

What the figure-spec skill makes the agent do

Normally an agent asked for a diagram either writes code for a chart or produces a loose illustration. This skill adds a specific workflow: the agent identifies the diagram's purpose, main entities, relationships, groupings and hierarchy, drafts a JSON spec describing nodes, edges, groups and canvas size, and then calls a bundled renderer (scripts/figure_renderer.py) to produce SVG.

The output is plain-text SVG. Because identical JSON always yields identical SVG for a fixed renderer version and fonts, you can version-control the spec and regenerate the figure whenever it changes. You can also edit the SVG by hand afterwards, although the skill itself says to change the JSON spec and re-render rather than edit the generated SVG.

  • Good fit: layered system architecture, hub-and-spoke designs, multi-plane diagrams, workflow and pipeline figures, audit cascades, and system topology.
  • Not a fit: bar, line or scatter data plots (the skill points to /paper-figure), natural or qualitative illustrations (it points to /paper-illustration), and quick flowcharts where Mermaid's lighter syntax is enough (it points to /mermaid-diagram).

Install the figure-spec skill

Download the ZIP for this skill from this page and unzip it. For a personal install, place the figure-spec folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder instead. The folder must contain SKILL.md and the scripts/ subfolder with figure_renderer.py.

If you use the Claude apps rather than Claude Code, you can upload the skill under Settings → Capabilities → Skills instead of copying files by hand.

  • Personal install: ~/.claude/skills/figure-spec/
  • Project install: .claude/skills/figure-spec/ inside your project
  • Files included: scripts/figure_renderer.py and SKILL.md

What the skill needs to run

The skill needs Python 3 to run the renderer and Bash shell access, because its invocation runs shell commands. Its SKILL.md lists optional reviewer tools (Codex, Grok, Antigravity or Claude review). These are used only if your workflow is configured to call them, so you can ignore them for basic diagram generation.

The renderer runs locally and does not use the network or API keys. The source lists the skill as running scripts but not using the network.

  • Python 3 (to run scripts/figure_renderer.py)
  • Bash shell access
  • Optional reviewer MCP tools, only if configured
  • No network access and no API keys required

How to trigger the skill with natural requests

You do not need to remember a command. The skill activates when your request uses one of its trigger phrases or asks for a precise, editable, publication-ready vector diagram. The skill also accepts an argument describing the diagram or a path to a file such as PAPER_PLAN.md or NARRATIVE_REPORT.md.

Be specific about what the boxes are, how they connect, and whether they form groups or layers. The more concrete the description, the more accurate the first spec will be.

  • "Draw the architecture diagram for our three-layer data pipeline as SVG."
  • "Make a workflow figure for the review loop: draft, check, revise, accept."
  • "Create a publication-quality pipeline figure with a decision diamond for pass or fail."
  • "Draw architecture: ingestion, storage and serving as stacked layers with a shared monitoring group."
  • Chinese trigger phrases in the description also work, such as 架构图, workflow 图, pipeline 图 and 确定性矢量图.

How the renderer works, step by step

The skill follows a fixed sequence. The agent first validates the spec, which catches problems such as missing fields, duplicate IDs, overlap warnings and invalid hex colors. It then renders to SVG. The source also shows converting the SVG to PDF with rsvg-convert for LaTeX inclusion.

Canvas sizes suggested by the skill are about 500×350 px for a single column, 900×500 px for a full-width figure, and 700×700 px for a tall topology. Edge clipping is shape-aware for rectangles, rounded boxes, circles, ellipses and diamonds, and labels support multiple lines including CJK characters.

  • Single-column figure: about 500×350 px
  • Two-column full-width figure: about 900×500 px
  • Tall topology: about 700×700 px
python3 "$FIGURE_RENDERER" validate /tmp/spec.json python3 "$FIGURE_RENDERER" render /tmp/spec.json --output figures/fig_arch.svg rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf

Safety notes: scripts and network

The skill runs a Python script and its invocation executes shell commands, so review it before installing, as you would any skill that runs code. The renderer is documented as fully local with no network calls and no external API.

Its allowed tools include Bash, Read, Write and Edit, plus optional reviewer MCP tools. Those reviewer tools only matter if you configure your workflow to call them. Keep the diagram spec and output files inside the folder you intend, since the agent writes files as part of the workflow.

  • Runs scripts: yes (figure_renderer.py)
  • Uses network: no
  • Shell access is required by design, so limit it to projects you trust
  • Reviewer tools are optional and used only when configured

Tips for better diagrams

Name node IDs clearly, because they are how edges and groups refer to nodes. Put nodes that belong together into a named group so the background frame clusters them cleanly. Keep colours distinct in both colour and greyscale, since the skill's visual review checks this.

When a render looks wrong, change the JSON and re-render instead of editing the SVG. This keeps the spec as the single source of truth and makes later changes reproducible.

  • Use clear, stable node IDs.
  • Group related nodes with a label and fill/stroke colours.
  • Check overlaps, clipped labels and arrow angles after each render.
  • Check grayscale readability before submission.

What people use it for

  • Drawing a layered system architecture figure for a research paper's methods section.
  • Documenting a data or ML pipeline as a left-to-right workflow figure that can be regenerated after changes.
  • Creating an audit cascade or flow-control diagram with a decision diamond for pass or fail outcomes.
  • Keeping technical documentation diagrams in version control as text specs and SVG output.

Frequently asked questions

Is the figure-spec skill free to use?

The source lists the skill under the MIT licence. It runs locally and the source does not mention any paid API or key requirement.

What do I need to install figure-spec?

You need Python 3 and Bash shell access. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.

Does figure-spec need an internet connection?

No. The source states the skill uses no network and runs fully local, with no API keys.

Can figure-spec make bar charts or line graphs?

No. The skill says data plots such as bar, line and scatter charts should use the /paper-figure skill instead.

How is figure-spec different from Mermaid?

Mermaid uses a lighter syntax suited to quick flowcharts. figure-spec needs a full JSON spec and more setup, but gives precise positions and editable vector output for formal figures.

Why does my diagram fail validation?

The validator reports issues such as a missing field, a duplicate ID, an overlap warning or an invalid hex colour. Fix the reported item in the JSON spec and run validate again.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use figure-spec if you need formal, editable, reproducible architecture or pipeline figures for papers or technical documentation and you are comfortable running a local Python script through an agent. Pick a lighter tool such as Mermaid for quick flowcharts, and a plotting or illustration skill for charts or artistic images.

Download the skill