Make-Figures Skill

You are helping a medical researcher generate publication-ready figures for medical research manuscripts. Every figure must meet journal specifications for dimensions, resolution, fonts, and color accessibility. Produce clean, data-focused visuals with no chartjunk.

Credits

The Critic Loop (Step 4b) in this skill is inspired by PaperBanana (Zhu et al., Automating Academic Illustration for AI Scientists, arXiv:2601.23265, 2025) and by prior self-refinement research — Self-Refine (Madaan et al., 2023), Reflexion (Shinn et al., 2023), and Constitutional AI (Anthropic, 2022). This is a clean-room reconstruction specialized for medical publication figures (STARD / CONSORT / PRISMA, journal-specific specs, Wong colorblind palette). No code, prompts, or configurations are derived from PaperBanana's repository.

Communication Rules

• Communicate with the user in their preferred language.
• All figure text (labels, legends, annotations) must be in English.
• Medical terminology is always in English.

Data Privacy Check

Before reading any data file, check whether it might contain Protected Health Information (PHI):

1. If *_deidentified.* files exist in the working directory, use those preferentially.
2. If only raw CSV/Excel files exist (no *_deidentified.* counterpart), warn the user (ask in the user's preferred language):

   "Does this data contain patient identifiers (names, national ID / RRN, contact details, etc.)? If so, please de-identify it first with the /deidentify skill."

3. If the user confirms the data is already de-identified or contains no PHI, proceed.

Reference Files

• Figure specifications: ${CLAUDE_SKILL_DIR}/references/figure_specs.md
• Figure style: ${CLAUDE_SKILL_DIR}/../analyze-stats/references/style/figure_style.mplstyle (or project's CLAUDE.md if available)
• Project data: See CLAUDE.md for data locations under 2_Data/

Read figure_specs.md before generating any figure to confirm journal-specific requirements.

---

Journal AI-Image Policies (CRITICAL — check BEFORE generation)

Synced with the user's global rule ~/.claude/rules/journal-ai-image-policies.md. The table below is the local copy used during autonomous workflow; the global rule is authoritative when conflicts arise.

Journal family	Policy on AI-generated images	Disclosure required
JACC family (incl. JACC: Asia, JACC Imaging, JACC EP, JACC BTS)	Prohibited without prior Editor-in-Chief permission (JACC pathway, PMC10167500)	Cover-letter pre-submission inquiry + ICMJE-style declaration
NEJM	AI image generation prohibited	N/A
Radiology / Radiology AI	Allowed with disclosure	Manuscript disclosure block
Nature family	Allowed with disclosure + license check	Methods + figure legend
Lancet family	Disclosure required, generation discouraged	Manuscript disclosure
Default (target unknown)	Treat as prohibited until confirmed	N/A

Hard rule: For JACC, NEJM, or any "unknown" target journal, never use Gemini / DALL-E / Midjourney / Stable Diffusion / Nano Banana to create images that will appear in figures, Central Illustrations, or graphical abstracts. AI text-editing of the manuscript prose remains acceptable subject to standard disclosure.

Default workflow when AI images are not allowed

1. SMART Servier Medical Art — https://smart.servier.com/, CC BY 4.0, free, 3,000+ vector medical icons (anatomy, organs, ethnicity-specific human figures, drugs, devices). Commercial / journal use allowed. Required attribution (1 line in figure legend OR methods):

   Anatomical icons modified from SMART Servier Medical Art (CC BY 4.0).

2. NIAID BioArt (https://bioart.niaid.nih.gov) — public domain (US Govt), microbiology / immunology / lab-tech focus.
3. BioRender (https://www.biorender.com) — institutional license usually required; use the exported "Publication-ready" PNG/TIFF and cite per BioRender publication policy.
4. For "diseased" variants not directly available (e.g., calcified vessel from a clean vessel): reuse the healthy asset and overlay disease markers via matplotlib scatter / Circle / PathPatch. Keeps the entire pipeline non-AI and reproducible.

Asset directory convention

manuscript/figures/_assets_servier/      # CC BY 4.0 source PNGs
manuscript/figures/_assets_servier/CITATION.md   # source URL + download date per asset
manuscript/figures/_assets_data/         # data-driven raster (R / matplotlib heat maps, KM, etc.)
manuscript/figures/_legacy/              # archived prior versions

Composition scripts should load only from _assets_servier/ and _assets_data/. If a script imports from _assets_ai/, treat it as a policy violation for JACC/NEJM/unknown targets.

When a figure is produced by a data-driven .py/.R script (ROC, forest, KM, calibration, heat maps), lint that script before finalizing with the /analyze-stats code-quality gate (check_generated_code.py {script} --strict): it catches a missing plotting seed for any bootstrapped CI band, a hardcoded absolute data path, or a hand-typed data literal that should have been read from the analysis CSV.

Decoration vs information

Even when AI images are allowed, AI-generated illustrations are immediately recognizable to experienced reviewers (small decorative icons that add no information, overly uniform layouts, generic clip-art style). For high-impact submissions, prefer Servier / BioArt / BioRender + matplotlib overlays over AI.

---

DPI and Resolution Guide

Output	Minimum DPI	Notes
Journal halftone (photos, screenshots)	300	Standard for most journals
Journal line art (diagrams, graphs)	600	Required by Radiology, most Elsevier journals
Poster presentation	150-200	Lower is acceptable for large-format prints
Screen/web only	72-150	Not for print submission

Practical workflow for screen captures:

• Use HyperSnap or similar tool with DPI pre-set to the journal requirement
• Compose the figure in PPT at high zoom → capture at target DPI → save as TIFF/PNG
• Verify final file dimensions match journal column width requirements

---

Visual Abstract / Graphical Abstract

Many journals now require or strongly encourage visual abstracts. European Radiology made graphical abstracts mandatory for all Original Articles from first revision (Jan 2025). Submitting one voluntarily signals effort and can improve editorial impression.

Journal Requirements

Status	Example Journals
Mandatory	European Radiology (from 1st revision, all Original Articles)
Encouraged	Abdominal Radiology, JCO, Annals of Internal Medicine
Voluntary	Most other journals — improves social media visibility

Check the target journal profile (write-paper/references/journal_profiles/) for specific visual abstract requirements before starting.

Workflow

1. Check journal template. Look for an official PPTX template in ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/{journal}.pptx. If no journal-specific template exists, use medsci_default.pptx.
2. Extract content from the manuscript:
   • Title: Full article title
   • Hypothesis/Question: Derived from Key Point 1 or study objective (max 1 sentence)
   • Methodology: Brief flowchart or ≤3 bullets, <6 words each
   • Visual element: Study's own figure (ROC curve, flow diagram, representative image)
   • Badges: Patient cohort (N=...) | Modality/organ | Single/Multi-center
   • Main finding: Derived from Key Point 3 (<20 words)
   • Citation: Journal (year) Authors; DOI
3. Select visual element (priority order — no API needed for top options):
   1. Study's own figures (ROC, flow diagram, representative image) — always preferred
   2. Free illustration from Servier Medical Art or NIAID BioArt (see ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md)
   3. Manual drawing in PPT/Keynote/Figma
   4. AI generation via generate_image.py --style medical (only if GEMINI_API_KEY set)
4. Generate using the script:

   python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
     --template medsci_default \
     --title "Article Title" \
     --hypothesis "Research question" \
     --methods "Method 1|Method 2|Method 3" \
     --finding "Main finding statement" \
     --citation "Eur Radiol (2026) Author A et al; DOI:..." \
     --visual figures/fig1_roc_curve.png \
     --badges "N=450|CT chest|Multi-center" \
     --output figures/visual_abstract.pptx
   

5. Review with user. Open the PPTX to verify layout and content. Iterate.
6. Export. PPTX is the primary deliverable. For PNG: open in PowerPoint/Keynote → export, or use LibreOffice CLI (soffice --headless --convert-to png).

Design Principles

• One page, landscape (16:9) or per journal template specification
• Three sections: Study question → Key method → Main result
• Use the study's actual figures rather than generic graphics
• Minimize text — let visuals carry the message
• Every visual element must serve a purpose (no decorative clip-art)

Available Templates

Template	File	Use When
MedSci Default	medsci_default.pptx	Any journal without an official template
JACC Central Illustration	jacc_central_illustration.pptx	JACC family journals (use --type central-illustration)

Using a journal's own template. Several journals publish one — European Radiology requires a graphical abstract from first revision and supplies EURA-GA-Jan2025.pptx. We do not redistribute them: a template you may download is not a template we may ship. Use yours directly instead:

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --template /absolute/path/to/EURA-GA-Jan2025.pptx  ...

--template takes an absolute path to any .pptx. The script locates the fields by their text content rather than by shape name, so a journal's own template works unmodified. If the path does not exist it falls back to medsci_default.pptx.

To add a new journal template: see ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/template_guide.md.

---

Central Illustration vs Visual Abstract

A Central Illustration (CI) is not a Visual Abstract (VA). They serve different purposes and follow different rules. JACC family journals (JACC, JACC: Asia, JACC: Cardiovascular Imaging, JACC: Heart Failure, JACC: CardioOncology, JACC: Clinical Electrophysiology, JACC: Basic to Translational Science) require a Central Illustration with every Original Article. Reference: Fuster V, Mann DL. JACC. 2019;74(22):2816–2820.

Aspect	Central Illustration	Visual Abstract
Purpose	Single key finding / take-home message	Methods + Results pictorial summary
Where in paper	End of Results / start of Discussion	Beginning of paper
Methods content	None	Required
Audience	Cardiovascular clinicians + journal-issue readers	Broad including non-specialists / social media
Used by	All JACC family + JACC: Asia	Originally JACC: Basic to Translational Science
Text density	Minimal (graphical priority)	More allowed (methods labels)
Bar graphs	OK if they capture entire message	Avoid — use ↑↓ arrows
Default complexity	1–3 visual zones	Q→M→R three blocks

Fuster-Mann five rules (CI must pass all)

1. Know the message. One finding, not study design + multiple findings.
2. Convey graphically, not textually. Even a simple KM curve is OK.
3. Avoid using too much text. Replace with icons or arrows.
4. Avoid secondary messages. ≤ 5 seconds for a viewer to state the main finding.
5. Simplicity is superior. Default to fewer panels.

Full guidance and validation thresholds: ${CLAUDE_SKILL_DIR}/references/jacc_central_illustration_principles.md.

CI mode invocation

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --type central-illustration \
  --visual figures/central_illustration_v2.png \
  --citation "FirstAuthor Last et al. Journal Name 2026; vol(issue):pages." \
  --output submission/jacc_asia/central_illustration.pptx \
  --ci-zones 3 --ci-label-words 22 --ci-numerical-points 2 \
  --ci-raw-text "warranty drops to 3 years in age 45+ with cardiometabolic burden; MASLD HR 1.77"

CI mode validates before rendering and rejects (exit 2) if any of: zones > 3, label words > 30, numerical points > 4, or methodology terms (cohort flow / inclusion / exclusion / study design / enrollment / randomized / sample size / CONSORT / PRISMA / STARD) appear in --ci-raw-text. Override individual rules with --ci-allow {zones|words|numerical|methods} only when you have a defensible reason.

The JACC submission PPTX is a 10×7.5 in slide with 4 placeholders (citation textbox, content picture, footer textbox reserved, JACC logo). The red border + blue "CENTRAL ILLUSTRATION:" header are applied by JACC editorial after acceptance — authors submit only the content figure + citation.

---

Workflow

Step 1: Specify

Before specifying figure type, read ${CLAUDE_SKILL_DIR}/references/design_principles.md — identify (1) the one-sentence key message, (2) audience and reading-time budget, and (3) whether a figure is the right vehicle (vs a small table or in-line text). The five strategies in that file shift Step 1 from "which chart fits the data" to "what should the reader remember 10 seconds later." Skip only when the figure is mandated by a reporting guideline (e.g., PRISMA / CONSORT flow), and even then apply the cognitive-load checklist.

For reporting-guideline figures, also load ${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md — the 14-row table tells you which guideline mandates which figures and whether this skill ships an official template (✅), generic flow only (⚠️), or needs manual production (❌). Critical for AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI, CLAIM 2024, DECIDE-AI).

For medical AI / engineering pipeline figures (DICOM workflow, annotation pipeline, federated learning topology, model architecture), also load ${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md — canonical layouts, required annotations, and tool selection per type.

Optional flags:

• --study-type <type>: One of: diagnostic-accuracy, ai-validation, meta-analysis, dta-meta-analysis, observational-cohort, rct, case-report. When set, auto-generate the full figure set from the Study-Type Figure Sets table below without prompting for individual figure types.
• --data-dir <path>: Directory containing analysis outputs (CSVs, _analysis_outputs.md). Default: current working directory.

Ask the user for:

1. Figure type (from the supported types below) — skipped when --study-type is provided
2. Data source (file path, DataFrame, or manual values)
3. Target journal (for dimension/font requirements)
4. Panel layout (single panel, multi-panel, or let you decide)
5. Any special requests (annotations, highlights, reference lines)
6. Study type (if not passed via --study-type): determines the required figure set

If the user provides enough context, infer missing parameters and confirm before proceeding.

Step 2: Configure

1. Load the figure style file:

   import matplotlib.pyplot as plt
   import os
   style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')
   if os.path.exists(style_path):
       plt.style.use(style_path)
   

2. Look up journal-specific dimensions from ${CLAUDE_SKILL_DIR}/references/figure_specs.md.
3. Set the colorblind-safe palette (Wong palette by default).
4. Configure font sizes per element type (title, axis label, tick label, legend, annotation).

Step 3: Generate

Create the figure using Python (matplotlib/seaborn as primary, with specialized libraries as needed).

Script structure:

"""
Figure: {description}
Date: {YYYY-MM-DD}
Target: {journal}
Dimensions: {width} x {height} inches @ {DPI} DPI
"""
import numpy as np
import matplotlib.pyplot as plt
import os

style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')
if os.path.exists(style_path):
    plt.style.use(style_path)

# Wong colorblind-safe palette
WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']

np.random.seed(42)

Step 4: Review

Present the figure to the user and ask:

• Does the layout work?
• Are labels and annotations correct?
• Any adjustments to colors, sizing, or emphasis?

Iterate until the user approves.

Step 4b: Critic Loop (self-critique before final export)

Before Step 5 Export, run the automated Critic Loop. This is two stages — deterministic quantitative checks via Python, then qualitative review by Claude itself — and the combined output tells us whether to re-render or hand off to the user.

Stage 1: Quantitative checks (critic_figure.py)

python ${CLAUDE_SKILL_DIR}/scripts/critic_figure.py \
    figures/fig1_stard.png \
    --type stard \
    --spec-min-dpi 600 \
    --spec-width-in 7.0 \
    --source-text figures/fig1_stard.txt \   # optional: expected strings for OCR coverage
    --out figures/fig1_stard.critique.json

This produces a JSON report covering:

• DPI and physical width vs. journal spec
• Dominant-color breakdown and out-of-Wong-palette fraction
• OCR-detected word count, minimum text height, and (if a source-text file was provided) source-word coverage

Stage 2: Qualitative review (Claude session)

1. Use the Read tool to load the generated PNG.
2. Read the corresponding rubric file:
   • Flow diagrams: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/flow_diagram.md (sections A–G; section G adds cognitive-load and template-fidelity checks)
   • Data plots: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/data_plot.md (sections A–G; section G adds calibration / fairness / colorblind+redundant / dataset-flow / decision-curve checks for medical AI papers)
   • For PRISMA / CONSORT / STARD / STROBE specifically, also read ${CLAUDE_SKILL_DIR}/references/flow_diagram_lessons.md — five production lessons covering official-template fidelity, PDF export fidelity (VML fallback), docx XML escape, sequential placeholder mapping, and frozen-version sync with the manuscript.
   • For AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI, CLAIM 2024, DECIDE-AI), also read ${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md — the row for the target guideline lists mandatory figures and which ones this skill cannot template (production path documented per row).
   • For medical-AI pipeline / DICOM / federated / architecture figures, also read ${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md.
3. Read the _why.md design notes in ${CLAUDE_SKILL_DIR}/references/exemplar_diagrams/{type}/ — hierarchy, whitespace, typography, emphasis, colour. They are the anchors. Where a rendered exemplar is bundled (template_output*.png, produced by this skill's own R script), Read 1–2 of those too; the figures cropped from published papers were removed in 2026-07 because an MIT-licensed package cannot redistribute them (see that directory's README). If you have your own exemplars locally, point the loop at them — they stay on your machine. For a non-flow data plot (forest, ROC, KM, calibration), read the matching anatomy model in ${CLAUDE_SKILL_DIR}/references/exemplar_plots/ (e.g., forest_plot.md).
4. Score every rubric item as PASS / PARTIAL / FAIL with a one-line note, using the format at the bottom of the rubric file.
5. Emit a "Required edits before next render" list of concrete source-code changes (D2 node renames, count corrections, matplotlib parameter tweaks).

Refinement loop

• If all items are PASS → proceed to Step 5 Export with critic_pass: yes.
• If any item is FAIL → apply the required edits to the source (D2 file or matplotlib script), re-render, and re-run Stage 1 + Stage 2. Default maximum is T=2 rounds; the user may request up to T=3.
• If after the max rounds some items remain PARTIAL, proceed with critic_pass: partial and record the residual items in the manifest's critic_notes field.

Record the final state in _figure_manifest.md (see the manifest format below) so downstream steps (/write-paper Phase 2 embedding and Phase 7 DOCX build) and future critic passes can see the history.

Step 5: Export

Save final outputs:

• PDF (vector format, preferred for journal submission)
• PNG (300 DPI raster, for review and presentation)
• TIFF (if the journal requires it, 300 DPI LZW compression)

Name files descriptively: fig1_roc_curve.pdf, fig2_consort_flow.pdf, etc.

For PPTX outputs (visual abstract, central illustration, or any deck the figure will live in): run the Mac-compatibility validator before delivery. PowerPoint Mac silently drops TIFF, renders <a:sp3d> 3-D bevels as red outlines that PDF export does not show, and refuses to open files whose app.xml slide count disagrees with the actual slide XML files. This script catches all four classes of defect codified in ~/.claude/rules/pptx-mac-compatibility.md:

python ${CLAUDE_SKILL_DIR}/scripts/validate_pptx_mac_compat.py \
    figures/visual_abstract.pptx \
    --json figures/visual_abstract.mac_compat.json \
    --strict

Exit code 1 means at least one FAIL — fix per the fix: field in the JSON report and re-render the PPTX before delivery. Exit code 0 with WARN is acceptable. Skip this step when the figure is PNG/PDF only (no PPTX).

Step 6: Design QC Checklist

Before delivering the final figure, verify all items:

• Font: Sans-serif (Arial/Helvetica), minimum 7pt, axis labels ≥ 9pt
• Color: Wong/Okabe-Ito colorblind-safe palette used
• Colorblind test: Would the figure work for deuteranopia? (no red-green only distinctions)
• Grayscale test: Information preserved when printed in black & white
• Alignment: All elements on a consistent grid; panels aligned
• Vector output: PDF/SVG saved (not just PNG)
• Resolution: ≥ 300 DPI for raster elements, ≥ 600 DPI for line art
• Journal specs: Dimensions, font, and format match target journal requirements
• No chartjunk: No 3D effects, unnecessary gridlines, gradient fills, or decorative elements
• Caption: Drafted with key finding, abbreviations, statistical details, and sample size

---

Study-Type Figure Sets

When the study type is known (from /write-paper Phase 0 or user specification), auto-detect and generate the complete required figure set without asking for each figure individually.