0x6869726f6b69/claude-skills

Nature-grade Figure Composer

A figure is not merely a "display of results," but a means to visually demonstrate a scientific claim. This skill reassembles scattered analysis results into a narrative where "1 Figure = 1 Claim," and delivers files that meet Nature-series technical specifications.

<SKILL_DIR> is the directory containing this SKILL.md. Requirements: Python 3.9+, matplotlib, numpy, pandas, Pillow, PyMuPDF (pip install pymupdf), scipy (for 95% CI).

Bundled Resources

Path	Content	When to Read
references/guidelines.md	User-specified plotting guidelines (7 principles), Nature technical specs, final checklist	Read before planning, re-read during QA
references/storyboard.md	How to organize results into figures, Figure 1 archetypes, layout types, delegated design procedure	Step 3
references/charts.md	Claim types → chart types, uncertainty/axes, maps, nfig code examples	Step 3 (selecting format), 5
references/captions-tables.md	Caption, Table, and Supplementary material writing guidelines with examples	Step 7
scripts/inventory.py	Result file inventory + numbered contact sheet	Step 1
scripts/nfig.py	Style- and meaning-fixed color palettes, panel labels, plotting helpers, automatic QA	Steps 4–6
scripts/assemble.py	Composite existing PDF/SVG/PNG into multi-panels while preserving vectors	When some panels cannot be re-rendered
scripts/check_figure.py	Finished file spec check + color vision simulation images	Step 6
scripts/make_table.py	CSV → booktabs LaTeX / Markdown table	Step 7
assets/figure_plan_template.md	Figure plan template	Step 3
assets/style_template.py	Template for shared conventions (display names, color ranges, axis labels) across all figures	Step 4
assets/layout_example.json	Layout example for assemble.py	When using assemble

Workflow

Step 1 — Inventory Results (Quickly, before asking questions)

python <SKILL_DIR>/scripts/inventory.py <project_root> --sheet paper_figures/_inventory --out paper_figures/_inventory/inventory.md

• Use Read to view paper_figures/_inventory/contact_sheet_*.png and understand what each result shows. The report's "made by / read by" columns allow tracing from a figure → generating script → source data (needed for re-rendering).
• If manuscripts, READMEs, or notes exist, read them to grasp the research question, proposed method, and claims.
• Append a one-sentence observation to each result (e.g., #6 benchmark.csv → Proposed method achieves highest accuracy on all 3 datasets, +6 pt). This becomes material for Step 2 selection and Step 3 planning.
• If no results are found, ask about their location together in Step 2.

Step 2 — Interview (Must be done after skill activation)

The end user has the final say on how to organize the figure, so confirm before plotting. However, do not re-ask questions that are already answered in the activation message. If AskUserQuestion is available, use it; otherwise, present numbered questions as text and wait for a reply. Create options from Step 1's inventory specifically (including file numbers and observations).

1. Scope (required): "Which results do you want to combine into one figure?"
   • Delegate: Design the entire figure composition (Fig. 1–N + SI) from all results (Recommended)
   • 1–2 candidate groups built from inventory (e.g., "Performance comparison: #1 accuracy_bar, #6 benchmark.csv")
   • Free form (Other): Specify like "#1, #4, #6 in one figure"
2. Claim: "What is the single most important message of this figure?" — 1–2 estimated claims + delegate
3. Publication size: 2-column 183 mm (Recommended) / 1-column 89 mm / 1.5-column 120–136 mm / delegate
4. Outputs (multiple selection): Figure (PDF+SVG+PNG) / Caption (English) / Table / SI candidate list

Handling of responses:

• If scope (Q1) is already specified in the activation message, proceed with defaults for Q2–Q4 (claim is estimated, 183 mm, Figure+Caption), and only ask when a judgment is needed.
• For "delegate" or items without instructions, Claude decides which results to adopt, how to arrange them, and how to compile them. Follow the "delegated design procedure" in references/storyboard.md.
• If told "proceed without asking," treat all items as delegated.
• Figure text and Caption default to English (since the publication target is in English). Conversations are conducted in the user's language.

Step 3 — Figure Plan (Storyboard)

Before writing code, read references/storyboard.md and write paper_figures/figure_plan.md in the format of assets/figure_plan_template.md. Include:

• The overall flow of the paper (What → How → Why → Performance → Impact) and the role of each figure
• For each Figure: A one-sentence claim (which becomes the caption's title sentence), panel table (label / content / chart type (selected from references/charts.md §1) / data source / hero or support), mosaic and dimensions, role of color
• Results excluded from the main text (SI-bound) with reasons. Do not hide limitations or failures; place them in the main text's limitation panel or SI
• Missing information (n, definition of error bars, statistical tests, units) listed as [AUTHOR TODO]

Present a brief table of the plan in chat. In the case of delegation or when the plan matches the user's specifications, proceed to plotting without waiting for confirmation, adding "the plan can be changed later." Only stop and consult if the specified results do not support the claim, or if the specifications contradict each other.

Step 4 — Fix Common Styles

• Copy nfig.py into paper_figures/src/ (so that figure scripts can re-run without this skill).
• Fix the entire paper's method/condition → color/marker/line style in one paper_figures/figure_style.json. If color meaning changes between figures, readers must re-read legends every time, so use this across all figures.

import style                      # paper_figures/src/style.py (path is independent of execution location)
pal = nfig.Palette.load_or_build(style.PALETTE,
        proposed=["Ours"], highlight=["SOTA-X"],
        baselines=["Base A", "Base B"], references=["Oracle"])

• proposed = accent color (subdued vermilion), highlight = the single strongest baseline in blue, other baselines = gray shades + markers/line styles, reference (theoretical upper limit/chance level) = black dashed line.
• Existing assignments remain unchanged; new names are appended. For non-method categories (e.g., datasets), do not reuse the same colors; distinguish by position, panel division, or markers.
• Shared "display conventions" for all figures are centralized in paper_figures/src/style.py (copy assets/style_template.py) and imported by each figure script: data names → display names ("PISurr (ours)" → "PISurr"), color ranges for the same quantity (e.g., TEMP_LIM = (300, 345), ERR_LIM = (0, 6)), axis labels with units. Writing them per figure causes inconsistencies.

Step 5 — Plotting

As a rule, re-plot from source data using nfig. Compositing existing PNGs results in inconsistent fonts, line widths, and colors, and scaling down can easily make text smaller than 5 pt. Select chart types from references/charts.md.

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))   # works from any execution location
import nfig
nfig.use_style()                                          # Arial 7/6 pt, 0.5 pt axes, TrueType 42
fig, axd = nfig.figure("double", 120, mosaic="aab;cde")  # draw at final publication size
# ... each panel (recipes from charts.md) ...
nfig.shared_legend(fig, pal.handles(["Ours", "SOTA-X", "Base A"]))  # one legend per whole figure
nfig.label_panels(fig, axd)          # call last: a, b, c… 8 pt bold, aligned by row/column
nfig.save(fig, "paper_figures/fig2")       # .pdf/.svg/.png + automatic QA report

label_panels fixes (locks) the layout, so add legends, annotations, and colorbars before it.

• 1 Figure = 1 script (paper_figures/src/fig2.py). Ensure reproducibility from data loading to saving.
• Draw at final size; do not scale down later. Do not use bbox_inches="tight" as it changes width.
• Make the hero panel the largest, placed in the upper-left or top row. Ensure same-type graphs have consistent size, axis ranges, and ticks.
• For figures where row-by-row panel types differ (e.g., a schematic band / image/map column / chart), do not use a single mosaic; instead, use nfig.figure("double", 120, rows=[("a", 0.8), ("bcdef", 1), ("g", 1)]) to compose row by row. A single grid would apply the tick label padding from one column to other rows in the same column, potentially squashing images or maps. If rows are of the same type, keep a single mosaic (column edges align).
• For fields like temperature and error maps, use nfig.field (color range from style.py shared values) + nfig.colorbar, using one colorbar for the same quantity. Photos and microscope images use nfig.image_panel.
• Panels that cannot be re-plotted (external tool schematics, microscope images, figures with no remaining data):
  • If few, embed them with nfig.image_panel(ax, path) (becomes raster).
  • To keep them vector, composite nfig-drawn panel PDFs and external PDFs using scripts/assemble.py (assets/layout_example.json, paths relative to the JSON). Draw nfig panels at the same dimensions (mm) as the post-composite cell to keep scaling ≈ 1. Adjust cell ratio and height until QA reports "text below 5 pt," "below 300 dpi," and "cell mostly empty" are eliminated.
  • Report to the user why re-plotting was not possible and note that it could be fixed if source data were available.
• Data integrity: do not alter values, do not cherry-pick favorable results, bars start from 0, avoid axis truncation that exaggerates differences. Images may only undergo uniform global adjustments and cropping (no local editing, compositing, or generative AI editing).

Step 6 — QA and Revision Loop (Minimum 2 Rounds)

1. Automatic check: In addition to the nfig.save report, run: python <SKILL_DIR>/scripts/check_figure.py paper_figures/fig2.pdf. Resolve all ERRORs; for WARNs, only keep those with an intentional reason, and record the reason.
2. Visual inspection: Use Read to view paper_figures/qa/fig2_preview.png (at final display size) and fig2_access.png (deuteranopia, protanopia, grayscale). Verify against the final checklist in references/guidelines.md. Pay special attention to: whether the claim is conveyed in 3 seconds / whether the hero is most prominent / whether the flow reads upper-left to lower-right / any overlapping or clipping of text/lines, misalignment / meaningless white space or overcrowding / whether differences are distinguishable under color vision deficiencies and grayscale.
3. Fix, regenerate, and re-inspect. Finally, ask yourself from the reviewer's perspective: "Does this figure and caption alone convince me of the claim?"

Step 7 — Caption, Table, Delivery

• Write the Caption in the format of references/captions-tables.md in paper_figures/captions.md (bold title sentence = claim → each panel in order → definition of symbols, colors, abbreviations → n, error bars, statistical tests).
• Convert precise numerical comparisons to Tables: scripts/make_table.py (booktabs, no vertical rules, only bold for best values). Long-format data with one row per seed can be summarized as mean ± s.d. and n using --groupby and --stat.
• Report to the user: list of created files, each figure's claim and panel structure, results sent to SI with reasons, [AUTHOR TODO] (e.g., unconfirmed statistical information), and any retained WARNs with reasons.

Output Directory (Default)

To avoid mixing with or overwriting the user's existing files (e.g., figures/), all output is organized under paper_figures/. If the user specifies a different location, follow that.

paper_figures/
├── figure_plan.md  figure_style.json  captions.md
├── src/            nfig.py, fig1.py, fig2.py, ...
├── fig1.pdf .svg .png, fig2.*, ...
├── tables/         table1.tex, table1.md
├── qa/             *_preview.png, *_access.png
└── _inventory/     inventory.md, contact_sheet_*.png

When in Doubt

• Decide what to show based on whether it serves as evidence for the claim. Results that do not constitute evidence, no matter how much effort went into them, should go to SI.
• For numerical improvements, always pair them with concrete examples showing what the improvement actually means.
• Showing not only the best results but also application conditions, limitations, and failure cases increases the credibility of the claim.
• When in doubt, choose simplicity: reduce colors, reduce text (move explanations to the Caption), share legends.