publication-chart-skill - SKILL.md Agent Skill

name: publication-chart-skill description: This skill should be used when the user asks for a publication-quality scientific figure or table, wants help choosing the right chart for results, needs a paper-ready pubfig or pubtab workflow, wants a figure + companion table for a results section, wants an Excel sheet turned into publication-ready LaTeX, or wants an existing scientific figure/table reviewed and upgraded. version: 0.2.0

Publication Chart Skill

Goal

Use this skill to turn research results into publication-grade figures and tables with an end-to-end workflow.

Primary production stack:

pubfig for figures
pubtab for publication tables

This skill covers the full delivery chain:

understand the scientific communication goal,
choose the right artifact type,
map the task to pubfig, pubtab, or both,
generate concrete runnable instructions,
export paper-ready assets,
run publication QA,
propose targeted revisions.

Use this skill when

Trigger this skill for requests like:

“make a publication-quality figure”
“choose the right chart for these results”
“turn these results into a paper-ready figure”
“make a benchmark / ablation / calibration / forest / heatmap / scatter / line / bar figure”
“make a benchmark / appendix / ablation table from Excel”
“convert this Excel table into publication-ready LaTeX”
“prepare one summary figure plus one companion table for the results section”
“review and improve this scientific figure/table”
“I already have a weak chart / screenshot / draft plot — make it publication-ready”
“export panels for a paper figure”

Do not use this skill for

Do not use this skill when the task is mainly:

manuscript prose writing,
statistical testing without artifact design,
raw exploratory analysis with no publication deliverable,
Figma-first layout work before the figure/table content is solid.

For simple composite assembly after the figure content is already strong, use the optional secondary workflow in references/composite-assembly.md.

Primary contract

Inputs

Expect some combination of:

the scientific communication goal,
available data shape,
venue or style constraints,
whether the artifact is a figure, table, or mixed deliverable,
optional existing assets such as code, spreadsheets, .tex, screenshots, or draft plots,
whether the user needs a first draft, a publication-ready artifact, or a review/revision pass.

Outputs

The minimum useful output is:

the recommended figure/table form,
the recommended pubfig / pubtab route,
a minimal runnable code snippet or CLI command,
explicit export filenames and formats,
a publication QA summary,
and, when needed, a revision plan.

Default workflow

0. Probe the environment and artifact state

Before generating anything, identify:

whether pubfig or pubtab is actually available,
whether the user already has code / spreadsheets / .tex / screenshots,
whether the deliverable is a fresh build or a revision,
whether the result needs exact values, fast visual perception, or both.

Prefer the smallest environment check that helps execution. When the bundled helper script is available, use it first:

python3 scripts/ensure_publication_tooling.py --require pubfig --json
python3 scripts/ensure_publication_tooling.py --require pubtab --json

Equivalent manual checks are still acceptable when needed:

python -c "import pubfig; print(pubfig.__version__)"
python -c "import pubtab; print(pubtab.__version__)"
pubtab --help

Report the result clearly as available or missing.

If a dependency is missing and the task requires runnable execution:

auto-install it by default,
prefer the user’s active environment instead of guessing a random global interpreter,
use python3 scripts/ensure_publication_tooling.py --require ... as the default bundled route when the script is present,
let that helper choose uv vs python -m pip against the active interpreter,
re-run the availability probe after installation,
and only then continue with the artifact workflow.

Equivalent concrete commands include:

python3 scripts/ensure_publication_tooling.py --require pubfig
python3 scripts/ensure_publication_tooling.py --require pubtab
uv pip install pubfig
uv pip install pubtab
python -m pip install pubfig
python -m pip install pubtab

If auto-install fails, report the exact failure and then degrade gracefully.

Do not block on a full environment audit.

1. Classify the task

Classify the request along these axes:

artifact type: figure / table / mixed deliverable
maturity: exploratory draft / publication-ready generation / revision of an existing artifact
structure: single panel / multi-panel / figure-plus-table package
evidence mode: pattern perception / exact value lookup / both

Do not jump into plotting code before the communication target is clear.

Before plotting research results, lock the evidence contract:

primary scientific claim,
unit of analysis,
primary metric and metric direction,
whether repeated rows are independent,
missing cells or incomplete comparison blocks,
error-bar basis: subject, subject-task, fold, seed, run, or bootstrap sample,
whether exact values need a companion table,
whether the current evidence allows a winner/significance claim.

If these are unclear, ask or produce an audit recommendation instead of a polished figure. Do not create a paper-ready plot while the unit of analysis, missing-cell handling, or error-bar basis is unresolved.

2. Choose the representation

Choose the representation based on the scientific claim, not novelty or visual flair.

Common families:

comparison — grouped scatter, bar, line comparison, benchmark summary, companion table
ablation — grouped comparison, dumbbell, paired comparison, compact table
distribution — box, violin, raincloud, histogram, density, ECDF, QQ
relationship — scatter, bubble, contour2d, hexbin
trend — line, area
evaluation / diagnostic — calibration, ROC, PR, Bland–Altman, forest plot, volcano
composition / hierarchy — UpSet, stacked ratio, donut, radial hierarchy, circular grouped or stacked bars
table — benchmark table, ablation table, dataset summary, appendix table, error breakdown

Avoid weak defaults:

avoid pie/donut when exact comparison matters and a bar/table is clearer,
avoid radar unless the comparison is genuinely profile-like and low-cardinality,
avoid 3D, decorative gradients, and dense legends used only for style,
avoid forcing every result into a figure when a publication table communicates the evidence better.

If the request is ambiguous, explicitly state what scientific claim the artifact is supposed to support.

3. Map to the toolchain

Default mapping:

Figures → pubfig
Tables → pubtab
Mixed deliverables → use both, with each artifact carrying a distinct role

Tool roles:

pubfig is the default figure engine for scientific plots and paper-ready export.
pubtab is the default table engine for Excel ↔ LaTeX workflows, preview, and publication-ready table export.
Figma/composite assembly is an optional secondary branch for multi-panel finishing.

Route selection rules:

prefer Python for pubfig figure generation,
prefer CLI for pubtab when the task is file-driven,
prefer Python for pubtab when the task is already inside a notebook or scripted pipeline,
keep the figure and table responsibilities separate in mixed requests.

4. Generate concrete artifact instructions

Prefer the smallest production-ready artifact first:

minimal runnable Python for pubfig, or
minimal CLI/Python for pubtab

Then add publication parameters only when justified:

labels, caption, width, export format, backend, preview, panel packaging, or composite layout.

Keep filenames and suffixes explicit.

Good defaults:

figures: one pubfig call + one save_figure(...)
multiple figure outputs: batch_export(...)
tables: one pubtab xlsx2tex ... or pubtab.preview ...
mixed requests: one figure route + one table route, clearly separated

5. Define the delivery contract

For every response, make these explicit when possible:

the claim the artifact supports,
which part is handled by pubfig and which by pubtab,
the output filenames,
the output formats,
whether the artifact is draft / final / revision,
what still needs user-provided data or manuscript context.

6. Run publication QA

After generation, check:

title and legend density,
axis labels and units,
category ordering and baseline clarity,
color accessibility and grayscale robustness,
font / line-weight consistency,
caption readiness,
figure/table readability after downscaling,
panel consistency for multi-panel figures,
venue-fit issues such as width, crowding, or over-annotation.

The QA output must be concrete. Do not say “looks better” without naming why.

7. Revise

If the result is weak, revise with specific changes such as:

switch chart family,
remove chartjunk,
reorder categories,
move exact values into a table,
split a crowded panel,
add or simplify the caption,
change export width,
or convert the deliverable from figure-first to table-first.

Missing dependency behavior

If pubfig or pubtab is not available:

do not fail immediately,
first attempt automatic installation into the active environment,
prefer python3 scripts/ensure_publication_tooling.py --require ... when the bundled script exists,
explicitly state which dependency is missing,
state which install command or helper route is being used,
re-check availability after installation,
if installation succeeds, continue with the runnable workflow,
if installation fails, degrade to a design/specification workflow,
provide pseudocode or draft commands,
preserve the recommended figure/table structure,
still provide QA and revision guidance.

Composite assembly rule

Treat composite or Figma assembly as secondary:

use it when the user explicitly wants a multi-panel paper figure,
or when panel-level export and layout polishing are genuinely needed.

Do not escalate simple figure tasks into composite/Figma workflows by default.

Output style rules

Prefer direct, implementation-usable outputs.
Explain the why of chart/table choice briefly, then give the runnable route.
When execution matters, include a short environment status block such as pubfig: available/missing, pubtab: available/missing.
If a dependency is missing, state the exact helper command or install command, perform the installation, and report the post-install status.
When a table is stronger than a figure, say so explicitly.
When a figure is stronger than a table, say so explicitly.
When both are needed, assign them different communication roles.
Keep revision guidance actionable and falsifiable.

Recommended response shape

A strong response using this skill usually has 6 parts:

Artifact decision — figure / table / paired deliverable, and why
Tool route — pubfig, pubtab, or both
Minimal implementation — runnable code or CLI
Export plan — filenames, formats, width/backend/preview choices
Publication QA — what to verify before paper submission
Revision plan — what to change if the current artifact is weak

Resources

Load these as needed:

references/workflow.md — full end-to-end decision order and delivery contract
references/chart-selection.md — task-to-chart mapping and anti-patterns
references/execution-and-verification.md — environment probing, forced install behavior, and runnable verification
scripts/ensure_publication_tooling.py — bundled probe + auto-install helper for pubfig / pubtab
references/pubfig-recipes.md — shortest useful figure patterns and export routes
references/pubtab-recipes.md — shortest useful table routes and backend guidance
references/source-guides/pubfig-architecture.md — package layout and figure-generation boundaries from source
references/source-guides/pubfig-api-map.md — stable public pubfig surface and chart-family map from __init__.py
references/source-guides/pubfig-export-flow.md — figure export, publication sizing, and panel-export flow from source
references/source-guides/pubtab-architecture.md — package layout and forward/reverse conversion architecture from source
references/source-guides/pubtab-cli-api-flow.md — CLI-to-API control flow and batch/sheet behavior from source
references/source-guides/pubtab-backend-and-preview.md — backend/theme split and real preview compile pipeline from source
references/publication-qa-checklist.md — figure/table QA checklist
references/composite-assembly.md — optional multi-panel and Figma branch

For prompt-shaped examples, see examples/.