sci-figure

Semantic conference-quality main-figure workflow for AI/ML manuscripts.

One invocation produces one figure — typically the main method / pipeline / concept overview the user is currently designing. The visual story reads in 5 seconds per panel, at the standard expected by NeurIPS / ICML / ICLR. The deliverable is a .drawio source viewed in the drawio desktop app; auxiliary PNG assets are generated by an independent matplotlib script and embedded.

This skill does not produce a finished, perfect figure. It gives you a strong starting point — a coherent layout, a calibrated palette, asset stubs, a working .drawio source — that you finish by hand in the drawio app. Treat the output as a draft to refine, not a deliverable to ship. The Python layer is a semantic layout compiler; drawio XML is the editable target, not the authoring surface.

Prerequisites

• draw.io desktop app — the deliverable is a .drawio source you open and fine-tune in the app, and the CLI export (drawio --export) is what produces the bounded <figure>_review.png. Install from https://www.drawio.com/ (or brew install --cask drawio on macOS). The bundled CLI must be on PATH as drawio.
• uv — used by bootstrap_env.sh to create .venv/ and install dependencies. Install from https://docs.astral.sh/uv/ (or brew install uv / curl -LsSf https://astral.sh/uv/install.sh | sh).

Auto-deploy (paste into your agent)

Hand this prompt to a coding agent at your project root and it will install both skills and the Python environment, end to end:

Set up the sci-figure skill in this project. Steps:

1. Create .agents/skills/ if it doesn't exist.
2. Clone https://github.com/v1n4k/sci-figure.git into .agents/skills/sci-figure/.
3. Verify drawio is on PATH (which drawio) and uv is installed (which uv); if either is missing, stop and tell me how to install it for my OS rather than guessing.
4. Run bash .agents/skills/sci-figure/scripts/bootstrap_env.sh from the project root — this creates .venv/, installs sci_figure_lib plus the Tier 1 plotting stack, and best-effort clones the optional sibling drawio-skill backend if missing.
5. Confirm the install by importing sci_figure_lib inside .venv and printing its version. Don't start a figure yet — wait until I describe the manuscript.

Companion bundle: drawio-skill backend

This skill references but does not vendor the upstream drawio-skill bundle (CLI invocation patterns, export pitfalls, shape search, MathJax delimiter rules, fallback URLs). This bundle is optional convenience, not a generation dependency: the skill degrades gracefully without it and only loses export-troubleshooting reference material, not asset rendering or .drawio generation.

When installed, it should live at:

.agents/skills/drawio-skill/

— a sibling of this skill's directory. The skill resolves optional references through that path; if you move or rename it, those references simply won't be available.

bootstrap_env.sh tries to install this bundle automatically when it is missing. If git/network access is unavailable, it prints a warning and continues installing the sci-figure Python environment. To require this backend strictly, set SCI_FIGURE_REQUIRE_DRAWIO_BACKEND=1. To install it manually:

git clone https://github.com/Agents365-ai/drawio-skill.git \
  .agents/skills/drawio-skill

To later refresh upstream changes, the skill ships scripts/refresh_drawio_skill.sh:

# Just the nested SKILL.md (default — most-likely-to-change file)
bash .agents/skills/sci-figure/scripts/refresh_drawio_skill.sh

# Whole bundle (re-clone + overlay rsync, excluding .git; no delete)
bash .agents/skills/sci-figure/scripts/refresh_drawio_skill.sh --bundle

The refresh script requires .agents/skills/drawio-skill/ to already exist because refreshing is backend maintenance, not a prerequisite for figure generation. It refuses to create the directory from scratch so a typo can't silently overwrite something else. To force-refresh an existing backend during bootstrap:

SCI_FIGURE_REFRESH_DRAWIO=1 \
  bash .agents/skills/sci-figure/scripts/bootstrap_env.sh

Start a new figure

bash .agents/skills/sci-figure/scripts/new_figure.sh <name>
cd scripts/<name>
make assets
make xml     # build .drawio only, no drawio CLI export
make figure  # export review PNG when drawio CLI is available

Two stubs — generate_assets.py and generate_figure.py — plus a requirements.md decision log land in scripts/<name>/. Edit those. The lib stays in the skill. You do not need to bring your own requirements.md; the scaffold creates it, and the agent keeps it updated as design choices are made.

Workflow

The skill is explicitly human-in-the-loop — the agent generates candidates and implements your choice; design taste belongs to you.

+------------------+    +------------------+    +------------------+    +------------------+
| 1 read paper     |--->| 2 requirements   |--->| 3 layout choices |--->| 4 user chooses   |
+------------------+    +------------------+    +------------------+    +------------------+

+------------------+    +------------------+    +------------------+    +------------------+
| 5 assets+compile |--->| 6 drawio draft   |--->| 7 review / xml   |--->| 8 handoff/refine |
+------------------+    +------------------+    +------------------+    +------------------+

• Read paper — agent extracts the single novelty, conceptual structure, and notation symbols from the manuscript.
• Design — for a new main figure or ambiguous redesign, the agent presents ≥ 3 distinct layout candidates from references/layout.md, each citing an exemplar with similar conceptual structure. For a targeted revision, it proposes a local patch instead. Agent does not pick the winner.
• YOU — pick one, ask for a hybrid, or ask for another round.
• Log requirements — requirements.md records palette semantics, arrow meanings, asset/drawio boundary, and handoff state.
• Implement assets — generate_assets.py renders tight PNG thumbnails only for data-like visual content.
• Compile drawio — generate_figure.py uses semantic helpers (Rect, panel_box, wrapper_box, block_arrow, readout glyphs) to produce the editable .drawio.
• Review — make xml validates structure without drawio CLI; make figure exports the bounded review PNG when the CLI is available.
• Refine / handoff — script-driven edits continue until final human tuning starts; then record hand-tuned state before regenerating.

Read more

SKILL.md has the workflow at high level; references/*.md have the details (quality bar, asset strategy, notation, layout, typography, review-render bounds, trigger evals, anti-patterns).