TingxiYu/academic-figure-skill: A Skill Package That Pushes LLM Plots Toward Journal Specs

What problem academic-figure-skill actually solves

The gap it targets is not plotting. matplotlib and ggplot2 can draw any of the 29 chart types listed in the README. The gap is that a language model asked to "make me a figure" produces something that looks like a tutorial: default colour cycles, grid lines, a legend that repeats the axis labels, and a raster export at whatever size the code happened to produce. Rescaling that to a journal column afterwards distorts fonts and line weights.

The README states the design principle as "problem-driven rather than template-driven": each figure starts from a scientific question, and the chart type is argued from the number and structure of those questions. The intended user is a researcher who already works inside an AI coding assistant and wants the assistant to produce submission-ready output, not a demo. The package encodes Nature, Cell and Science conventions (Arial or Helvetica, single column 89mm, double column 183mm, vector PDF for line, scatter and bar charts, 300dpi TIFF or PNG only for genuinely raster content such as heatmap blocks or micrographs) so the model does not have to be told each time.

One caveat worth stating plainly: the README says the preview gallery was generated from the project's private data assets and is meant as style reference only. You are not looking at reproducible examples with published inputs.

The eight-step loop and where the Copy-First rule bites

The workflow in SKILL.md runs from Step -1 (requirement clarification, phrased as "what question should this data answer?") through Step 0a prototype classification, Step 0b data parsing, Step 1 chart-type argumentation, Step 2 runtime detection, Step 3 style injection, Step 4 asset retrieval, Step 5 rendering, Step 5.5 data validation, Step 6 quality verification, and Step 7 delivery of a vector PDF plus a 300dpi PNG preview, a statistics report and a QA report.

The mechanism that matters most is Step 4. Before generating any plotting code, the skill scans assets/figures/<type>/ for an existing production script. If one matches, it runs it natively: a .py file is executed as Python, a .R file is executed as R. The README calls this Copy-First and says the script is not translated and not downgraded in quality. Only when no production script matches does the skill fall back to cross-type parameter inheritance, borrowing visual parameters from a similar chart type in three classes: Class A hard parameters (colour, alpha, line width), Class B proportional parameters (font size, dimensions) and Class C logical parameters (legend on or off, grid on or off).

Prototype classification drives layout. The four paradigms are quantitative_grid, schematic-led, image plate + quant, and asymmetric_mixed. The README says these determine layout and hero-panel strategy, and that the panel carrying the core conclusion automatically receives greater visual weight while supporting panels are arranged secondarily. For mixed-language figures, R panels render to bitmap through the Cairo device and a Python compose.py layout engine assembles the panels at exact physical dimensions.

Installing academic-figure-skill in Claude Code

The README frames installation as cloning the repository to a stable path and installing the skill, and it stresses that the full install must keep the references/, scripts/, assets/ and install/ directories, because the skill depends on them for visual baseline injection, asset retrieval and cross-platform adaptation. The repository root contains LICENSE, README.md, README_EN.md, SKILL.md, assets/, install/, references/ and scripts/.

If Claude Code is not yet installed, the README gives these two commands first:

npm install -g @anthropic-ai/claude-code
claude

It then starts the clone step with a skills directory and a repository clone. The README excerpt ends mid-command, so the exact clone URL and the copy target are not shown in the available text; check the install section of the README in your own checkout before running it.

mkdir -p ~/ai-skills

After the clone, confirm the four dependency directories are present at the path where your assistant loads skills from. The install badge in the README lists Claude Code, Codex, Cursor and Copilot, so the package is not tied to a single assistant, but the README documents the Claude Code path in the most detail.

The first real use is a prompt that supplies data and a scientific question rather than a chart request. Expect the skill to ask clarifying questions before it writes code, because Step -1 is a clarification step, and expect it to stop at Step 5.5 if the data fails validation.

The data-validation gate is the most opinionated part

Step 5.5 pre-checks each panel and refuses to render if the data cannot support the chosen chart. The README gives three concrete thresholds: a volcano plot requires at least 10 significant differentially expressed genes, an AUROC curve requires at least 0.15 separation, and a heatmap must have variance across rows.

This is a design choice with a real cost. If your dataset is small, or your effect is genuinely subtle, the gate blocks output rather than producing a weak figure you could still inspect. There is no documented override in the README, so a user who disagrees with the threshold has to work around the skill, not configure it. Whether that is a feature or a nuisance depends on whether you trust the thresholds more than your own judgement about your data.

The four-pass QA protocol runs alongside it: Pass 0 scans for anti-patterns (AP-0-7), Pass 1 checks code-level compliance (CL-1-7), Pass 2 checks visual logic and data integrity (VI-1-6), and Pass 3 verifies rendered output (VV-1-5), for more than 30 checks in total. The README also describes a reviewer-simulation mode that examines finished figures across scientific clarity, visual hierarchy, colour accessibility, typographic readability and overall completeness, and grades feedback as must-fix versus suggestion. That grading is useful, but it is a model's self-assessment of its own output, which is a weaker check than an independent one.

Where academic-figure-skill is the wrong tool

The package is not a plotting library. There is no import academic_figure_skill line in the README, no Python API, and no CLI. If you want figures generated inside an existing pipeline, a scheduled report, or a CI job, this is the wrong shape of tool: it is a set of instructions and reference documents consumed by an AI assistant, and its output depends on that assistant's behaviour.

It is also a poor fit when the figure is trivial. A single bar chart with four categories does not benefit from a five-step clarification loop, a prototype classification, and four QA passes. The overhead is real, and the README's own principle of one core message per figure argues against packing extra panels in just to justify the workflow.

Two further limits come from the repository itself. There are no releases listed, so there is no versioned artefact to pin; you track the default branch. And the last push was on 2026-07-12, which is roughly two months before this writing. That is recent enough that the code is not stale, but the README does not describe a release process, a changelog, or a rollback path, and the repository is not archived. If you need a stable, versioned dependency, this is not that.

How it differs from writing matplotlib or ggplot code directly

The obvious alternative is the plotting library you already have. The difference is not capability but constraint. matplotlib will happily emit a 6x4 inch figure at 100dpi with the default colour cycle; academic-figure-skill's baseline fixes the font system, the colour scheme and the export specification before any code is written, and the README states that default matplotlib and ggplot palettes are disallowed in favour of two to four semantic primary colours plus one accent colour.

A second alternative is a journal's own figure-preparation checklist, which is a document a human reads and applies. academic-figure-skill turns that checklist into something an assistant executes, including the part humans skip: the README requires every figure to carry its n definition, central statistic (mean or median), spread measure (SD, SEM or 95% CI), test name, multiple-comparison correction and source-data traceability. That reporting requirement is arguably the more valuable half of the package, and it is the half a plotting library will never enforce.

The third comparison is to the project's own fallback path. When an asset match exists, the skill runs a maintained script; when it does not, the model writes new code guided by inherited parameters. Those two paths will not produce identical figures. The README does not claim they do, but a user comparing two figures from the same chart type should know which path produced each one.

Licence, maintenance and what an upgrade costs you

The repository is Apache-2.0, per the LICENSE file and the badge in the README. That is a permissive licence with an explicit patent grant, which matters if you fork the reference documents or the production scripts into an institutional template. The README does not discuss attribution requirements for generated figures, and nothing in the repository text addresses whether figures produced with the skill carry any licence obligation. That is a question for your institution, not something this article can settle.

Upgrade cost is the harder question. Because the skill is a directory of markdown, scripts and assets rather than an installed package, an update means replacing files, and the README's warning about keeping references/, scripts/, assets/ and install/ intact applies in reverse: a partial copy is a broken install. Any local edits you make to SKILL.md or to the 16 reference documents will conflict with an incoming version, and the repository does not document a merge strategy or a changelog.

The maintenance signal available is the last push on 2026-07-12. The repository is not archived. There are no releases, so there is no version number to compare against and no upgrade path described in the README. If you adopt this, budget for re-reading SKILL.md after each pull rather than assuming behaviour is unchanged.

Editorial conclusion

Adopt it if you already drive Claude Code, Codex, Cursor or Copilot and you want journal-style defaults (Arial or Helvetica, 89mm and 183mm column widths, vector PDF, 300dpi preview) applied without hand-tuning matplotlib or ggplot. Skip it if you need a library you can import and call from your own pipeline, or if your figures are simple enough that a dozen lines of matplotlib are faster than a five-step clarification loop. Before committing, verify three things in your own clone: that references/ and assets/figures/ survived the copy intact, that your runtime has both a Python and an R kernel if you plan to mix languages, and that the data-validation gate does not reject your dataset (a volcano plot needs at least 10 significant differentially expressed genes, and an AUROC curve needs at least 0.15 separation).

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. TingxiYu/academic-figure-skill on GitHub