scipilot-figure-skill: a Claude Code skill that picks the chart before it draws it

The problem is chart choice, not matplotlib syntax

The README opens with a claim worth taking seriously: the hard part of scientific plotting is rarely not knowing matplotlib, it is having data and not knowing which chart conveys the conclusion. That framing determines what this repository actually is. It is not a plotting library. It is a Claude Code skill, distributed as a directory of scripts and reference documents, that an agent loads when a user asks for a figure.

The target user is a researcher or graduate student who already has analysis output in a CSV or DataFrame and needs a submission-ready figure. The skill's own comparison table draws the line: a generic plotter takes "plot a bar chart" and calls plt.bar(), while this one profiles the columns first, asks what argument the figure should make, and only then renders. The repository is Python, MIT licensed, and sits in a family alongside scipilot-cite-skill and scipilot-writing-skill, with review, submit and read skills listed as planned.

An eight-step pipeline with an interception layer

The workflow documented in SKILL.md and the README runs from step 0 to step 7. Step 0 is understanding the task. Step 1 runs profile_data.py over the data to report column types, sample size, distribution, outliers and correlations. Step 2 consults chart_selection.md, a decision framework keyed on data shape plus argumentative intent. Step 3 reads journal_specs.md for column width, font size and DPI. Step 4 calls setup_style.py to apply a journal preset and configure CJK fonts. Step 5 draws using one of nine recipe families in plot_recipes.md. Step 6 runs a self-check. Step 7 exports through export_figure.py.

The most interesting layer sits between steps 2 and 3. The repository ships viz_pitfalls.md with fifteen documented anti-patterns, and the skill is meant to refuse some of them rather than comply. The README gives concrete examples: a mean bar chart over groups of five samples is intercepted and redirected to a box plot with stripplot overlay, because the mean hides the distribution and a reviewer will ask for individual points. Dual Y axes are rejected on the grounds that the correlation they imply is manufactured by the plotter. Pie and 3D charts become horizontal bars. Rainbow and jet colormaps become viridis or RdBu_r. When a figure carries more than one argument, the skill suggests splitting it.

That refusal behaviour is the product. Everything else here is a well-organized wrapper around libraries you already have.

Installing it into a skills directory and running a first profile

The README offers an agent-mediated install: paste the repository URL into Claude Code and ask it to install the skill. The manual route clones into the skills directory and installs the dependency list. The path below is the one the README uses.

git clone https://github.com/Haojae/scipilot-figure-skill.git \
          ~/.claude/skills/scipilot-figure-skill
pip install -r ~/.claude/skills/scipilot-figure-skill/requirements.txt

The requirements file pins matplotlib 3.7 or newer, seaborn 0.13 or newer, plotly 5.18 or newer, Pillow 10 or newer, numpy 1.24 or newer, pandas 2.0 or newer and scipy 1.10 or newer. SciencePlots, pypdf, kaleido and PyMuPDF are commented out and described as optional enhancements that degrade gracefully when missing. PyMuPDF is noted as needed only for visual_qa.render_preview() on PDFs that are already saved.

The first useful action is not drawing, it is profiling. Point the script at a CSV and name the grouping columns:

python scripts/profile_data.py results.csv --group group --group condition

You should get a report covering column types, sample sizes, distributions, outliers and correlations. That report is what the chart-selection step consumes, so running it first is the fastest way to see whether the skill's reasoning matches yours. Two other scripts are worth knowing before you trust the pipeline: setup_style.py --list-fonts enumerates the CJK fonts available on the machine, and check_figure.py audits exported files with a --min-dpi flag and a --strict mode.

The v2.1 self-check loop is the part with real teeth

Most plotting helpers stop when the file is written. This one adds a loop after rendering, and the README is explicit that the loop exists because nobody looks at the output until submission, at which point missing glyphs, clipped text, legends covering data and misaligned subplot labels all surface at once.

The loop has two halves. Programmatic checks live in visual_qa.audit_layout(), which the README says watches both the warning and logging channels to catch missing glyphs, and also checks for text running past the axes boundary and overlapping tick labels. Perceptual checks are handled by rendering a PNG and having the multimodal model read it, looking for legends that sit on top of data, subplot labels a/b/c that fail to line up, and colour schemes that collapse when converted to grayscale. Those are exactly the failures a program cannot detect, which is why the two halves are separate rather than merged.

A supporting utility, layout_tools.add_panel_labels(fig), places panel labels in unified figure coordinates so a/b/c/d align horizontally and vertically instead of being positioned by hand. The stated font fallback is that setup_style fixes the negative-sign box and configures a CJK font in every mode. The honest limitation is that the perceptual half depends on an agent that can read images; without that, you are left with the programmatic audit and a manual look at the PNG.

Journal specs, CJK fonts and the five hard rules

The skill encodes five rules the README presents as non-negotiable. Figures are drawn at final size rather than scaled afterwards, with the example figsize=(3.5, 2.625) given as Nature single column. Vector formats (PDF, SVG, EPS) are preferred for data plots, with TIFF or PNG reserved for photographs and JPEG ruled out. Colour defaults to Okabe-Ito with redundant encoding and a grayscale check before export. Font sizes sit at 7 to 9 pt with a 6 pt floor. Every figure caption must state whether error bars are SD, SEM or 95% CI, along with n and the statistical test.

CJK handling is a genuine differentiator for anyone writing for Chinese journals. The setup_style(lang='zh') call searches in a fixed priority order: Noto Sans CJK SC, then Source Han Sans SC, then SimHei, then Microsoft YaHei. If none is found, the README states that the skill raises a clear installation message rather than falling back silently, which is the right behaviour but also means a bare container image will fail loudly. For mixed typesetting of Songti with Times New Roman numerals, the README documents a serif_for_zh=True parameter.

The journal_specs.md reference covers Nature, Science, IEEE, Elsevier, PNAS and Chinese journals. What the README does not document is how those specifications are kept current when a publisher revises its author guidelines, and no release history is available to judge how often they have been revised.

Where it is the wrong tool

The skill is built around data plots. Nine recipe families, a chart-selection framework and a pitfalls list all assume you have a table with columns, sample sizes and distributions. If your figure is a schematic, a workflow diagram, a microscopy panel layout or a conceptual model, none of that machinery applies, and the profiling step has nothing to profile. The related searches for this space include diagram-drawing tools for a reason: those are a different category of problem.

There is also a hard dependency on the agent environment. This ships as a skill for Claude Code, Codex or Cursor, and the install path targets ~/.claude/skills/. If your team's workflow does not include one of those agents, the scripts under scripts/ still run, but the reasoning layer that profiles data, asks what argument the figure makes and intercepts bad chart choices is what you would be paying for, and that layer lives in the agent's reading of the reference documents.

Finally, the repository shows no retrieved releases. The README badges a v2.1.0 status, but there is no changelog or tagged release to consult, so anyone pinning a version should expect to pin a commit rather than a release artifact. The last push to the default branch was on 2026-06-15.

Alternatives and the actual difference in approach

SciencePlots is the closest thing to a direct comparison, and the relationship is not competitive. SciencePlots is a matplotlib style package that provides journal-themed rcParams; this repository lists it in requirements.txt as an optional enhancement and, per the README, builds its static output on matplotlib plus seaborn plus SciencePlots. If all you want is Nature-looking defaults, installing SciencePlots alone gets you there without an agent in the loop.

The difference is where the decision lives. A style package has no opinion about whether a bar chart of five-sample groups is the right figure. This skill does, and it will say so before rendering. That is also the trade-off: you are delegating a judgement call to a tool with a fixed pitfalls list of fifteen entries. If your field has conventions that conflict with that list, or if a reviewer has explicitly asked for the chart the skill wants to reject, you will be arguing with your own tooling. The README's example dialogue shows the skill offering the original option back to the user, which is the right escape hatch, but it depends on the agent honouring it.

For interactive or web-embedded output, plotly is already in the dependency list, so the choice is between static publication figures and interactive ones rather than between this project and a separate interactive library.

Licence and the cost of keeping up

The project is MIT licensed, copyright 2026 Haojae, with the LICENSE file at the repository root. That is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice are retained. It says nothing about the licences of matplotlib, seaborn, plotly or the optional SciencePlots and PyMuPDF packages, which you install separately and which carry their own terms. PyMuPDF in particular is not MIT, so anyone enabling the optional preview path for already-saved PDFs should read that licence on its own rather than assuming the MIT badge covers the whole stack.

Upgrade cost is mostly the reference documents. journal_specs.md, chart_selection.md, plot_recipes.md and viz_pitfalls.md are prose artifacts, not code, so keeping them accurate is editorial work rather than a dependency bump. The Python surface is small: profile_data.py, setup_style.py, export_figure.py, check_figure.py and the visual_qa and layout_tools modules. With no tagged releases retrieved, upgrades mean tracking the main branch, which makes the absence of a changelog the main practical friction for anyone running this in a shared lab environment.

Editorial conclusion

Adopt it if you already work inside Claude Code, Codex or Cursor and your bottleneck is deciding which chart carries an argument rather than writing matplotlib calls. Skip it if you need a stable released API, if your figures are schematic drawings rather than data plots, or if you cannot install a skill into your agent's skills directory. Before committing, run the profiling script on one real CSV and check that the recommended chart type matches what you would have chosen; then confirm on your own machine that setup_style resolves a CJK font, since the README states the skill raises an error rather than silently substituting when none is found.

Frequently asked questions

Official sources

1. Haojae/scipilot-figure-skill on GitHub
2. Issues
3. License: MIT
4. README