Skip to main content
skill CX Codex

paperbanana — Claude Code skill: academic figures, how to install

paperbanana turns method text or a paper into diagrams, statistical plots and figure reviews, picking the cheapest mode that still gets the job done.

MIT 108 installs ★ 61 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add akillness/jeo-skills --skill paperbanana -a claude-code
Open on GitHub

What paperbanana does

The skill covers the figure side of a paper: methodology diagrams, charts built from result tables, and a second opinion on images you already have. Its first move is routing. Rather than firing the full multi-agent loop, it picks the smallest mode that fits the request.

Generation runs in two stages. Planning writes a description of the target figure and a stylist borrows venue aesthetics; refinement then alternates between a visualizer drawing the image and a critic rewriting the description. --iterations sets how many passes run, --auto stops once the critic is satisfied, --optimize adds an input-cleaning step up front. Commands include plot for data, generate for one diagram, evaluate and polish for existing files, and batch or orchestrate for volume.

You need Python 3.10+ and a provider key. Diagrams want an image-generation key from OpenAI, Azure, Gemini, Atlas or OpenRouter, while charts need only a vision model key, so a CSV chart is the cheap way to start. Install into a virtual environment with the profile that matches the task, such as bash scripts/install.sh --profile diagram. Run generate without an image key and it has nothing to draw with.

What it helps with

  • turn a method section into a diagram
  • chart results from a CSV without an image-generation key
  • judge an existing figure against a human reference
  • restyle a figure to a venue's taste
  • produce the full figure set for a paper

Example prompts for the agent

  • Use paperbanana to draw the method diagram from method.txt
  • Plot accuracy from results.csv as a bar chart
  • Evaluate out.png against human.png and list the mismatches

How to install paperbanana

1Skills CLI (Vercel)

npx skills add akillness/jeo-skills --skill paperbanana -a claude-code

2Manually: put the files in place

~/.claude/skills/paperbanana/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/paperbanana/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about paperbanana

How do I install paperbanana in Claude Code?

Run npx skills add akillness/jeo-skills --skill paperbanana -a claude-code; the skill lands in ~/.claude/skills/paperbanana/SKILL.md.

What does paperbanana do?

It routes academic figure work: generating diagrams, plotting data, evaluating and polishing figures that already exist. Each request goes to the lightest mode that can handle it.

Do I need an image-generation API key?

Only for diagrams. Statistical plots work with a vision model key alone. The skill requires Python 3.10+ and runs best inside a virtual environment.

Source text

SKILL.md · MIT
---
name: paperbanana
description: >
  Route academic-figure work into the lightest workable PaperBanana mode instead of
  jumping straight to a full multi-agent generation run. Use when the user needs
  publication-quality methodology diagrams, statistical plots, figure evaluation,
  polishing an existing figure, batch/sweep generation, or a full-paper figure package
  from text or PDF. Even if the user does not say "paperbanana" — also triggers on:
  academic figure, methodology diagram, publication figure, generate diagram from paper,
  statistical plot from CSV, figure evaluation, polish figure, NeurIPS/ICML figure,
  arxiv illustration, plan-then-refine diagram pipeline.
allowed-tools: Bash Read Write Edit Glob Grep WebFetch
compatibility: Requires Python 3.10+ and works best in a virtual environment. Diagram generation needs an image-gen provider key (OpenAI/Azure/Gemini/Atlas/OpenRouter); statistical plots need only a VLM key. Studio, PDF, and MCP surfaces require extras.
license: MIT
metadata:
  tags: paperbanana, academic-figures, diagram-generation, statistical-plots, multi-agent, vlm-as-judge, mcp, cli, publication, python
  version: "1.0"
  source: https://github.com/llmsresearch/paperbanana
---

# paperbanana — routing-first academic illustration

> **Keyword**: `paperbanana` · `methodology diagram` · `statistical plot` · `figure evaluation` · `plan-then-refine`
>
> This is an unofficial community implementation of the PaperBanana paper (arXiv:2601.23265).
> Respect provider terms, API budgets, and each venue's figure/reuse policies.

PaperBanana turns text or a paper into publication-quality figures with a **two-phase,
multi-agent, plan-then-refine pipeline**. It is most useful when you choose the
**smallest workable mode** instead of always running the full generation loop:

- render data-driven charts with `plot` (matplotlib code, no image-gen key) before spending image credits
- fix an existing figure with `polish` or `evaluate` before regenerating from scratch
- generate a single diagram with `generate` before reaching for batch/sweep/orchestrate
- escalate iterations, candidates, and `--optimize` only on evidence, not by default
- route out to a vector editor, TikZ, or a human designer when generative figures are the wrong tool

## When to use this skill

- The user wants a methodology/architecture diagram from a `.txt`, `.md`, or `.pdf` and you must pick the lightest generation path
- The user has tabular results (CSV/JSON) and wants a chart — cheaper than a diagram because no image-gen provider is needed
- The user already has a figure and wants it judged (`evaluate`) or improved (`polish`) rather than re-created
- The user needs many figures (a manifest batch, a parameter sweep, or a whole-paper figure package)
- The user wants PaperBanana exposed to an agent/IDE via the MCP server or Claude Code skills
- The user keeps drifting toward hand-drawing every figure, hard-coding one provider, or maxing iterations/candidates and needs an honest route-out

## Instructions

### Step 1: Capture one intake packet before choosing a mode

Collect the minimum packet:

- **Artifact class**: a methodology diagram, a statistical plot, an existing figure to fix/judge, many figures, or a full-paper package
- **Source**: raw method text, a paper (`.pdf`/`.md`), a data file (CSV/JSON), or an existing image
- **Budget/keys**: which provider key is available (VLM-only vs image-gen), and any USD cap
- **Quality need**: quick draft vs auto-refine to critic satisfaction vs multi-candidate fan-out

Use this escalation ladder (smallest first):

1. Data → chart? Use `plot` / `plot-batch` (VLM-generated matplotlib, no image-gen key)
2. One diagram from text/PDF? Use `generate`
3. Have a figure already? Use `evaluate` (judge) or `polish` (guided edit), not a fresh run
4. Many diagrams/plots from a manifest? Use `batch` / `plot-batch`; sweep params with `sweep`
5. A whole paper's figure set? Use `orchestrate`
6. Generative figures are the wrong tool (exact vector art, trivial chart, brand-locked design)? Route out

Detailed packet examples and route-outs live in [references/intake-and-route-outs.md](references/intake-and-route-outs.md).

### Step 2: Install only the profile you need

Use a virtual environment unless the user explicitly wants a system install.

bash
bash scripts/install.sh --profile plot      # VLM-only: statistical plots
bash scripts/install.sh --profile diagram   # image-gen provider for diagrams
bash scripts/install.sh --profile pdf        # + PyMuPDF for PDF inputs
bash scripts/install.sh --profile studio     # + Gradio local web UI
bash scripts/install.sh --profile mcp        # MCP server surface
bash scripts/install.sh --profile all        # only when the full surface is truly needed


Then set exactly one provider key (`OPENAI_API_KEY`, `GOOGLE_API_KEY`, `ATLASCLOUD_API_KEY`, …).
Provider selection and config live in [references/providers-and-config.md](references/providers-and-config.md).

### Step 3: Understand the pipeline before turning knobs

Every diagram run is the same plan-then-refine loop, so tune stages instead of guessing flags:

- **Phase 0 — Input Optimization** (`--optimize`, optional): Context Enricher structures raw method text; Caption Sharpener tightens the caption. Two parallel VLM calls.
- **Phase 1 — Linear Planning**: Retriever picks reference examples → Planner writes a target description via in-context learning → Stylist applies venue aesthetics.
- **Phase 2 — Iterative Refinement**: Visualizer renders an image → Critic revises the description; repeat for `--iterations` (default 3) or until satisfied with `--auto`.

Full agent-by-agent detail lives in [references/pipeline-and-agents.md](references/pipeline-and-agents.md).

### Step 4: Run the lightest mode that fits

bash
# Cheapest: statistical plot from data (no image-gen key)
bash scripts/run.sh plot --data results.csv --intent "Bar chart of accuracy across benchmarks"

# Single methodology diagram from text
bash scripts/run.sh generate --input method.txt --caption "Overview of our framework"

# Add optimization + auto-refine ONLY when a plain run underdelivers
bash scripts/run.sh generate --input method.txt --caption "Overview" --optimize --auto


The full command surface (`generate`, `plot`, `batch`, `plot-batch`, `sweep`, `orchestrate`,
`composite`, `evaluate`, `polish`, `venues`, `studio`, `setup`, `data`) with flags lives in
[references/modes-and-cli.md](references/modes-and-cli.md).

### Step 5: Fix before you regenerate

When a figure already exists, do not rerun the whole pipeline:

bash
# Judge an existing figure against a human reference (VLM-as-Judge)
bash scripts/run.sh evaluate --generated out.png --reference human.png \
  --context method.txt --caption "Overview of our framework"

# Guided edit against a venue style guide (image-edit capable provider)
bash scripts/run.sh polish --input figure.png --venue icml --iterations 2


Evaluation dimensions (Faithfulness, Readability, Conciseness, Aesthetics) and venue style packs
live in [references/evaluation-and-venues.md](references/evaluation-and-venues.md).

### Step 6: Escalate to batch, sweep, or orchestrate only when scale is the real problem

- `batch` / `plot-batch` — many items from one manifest; optional `composite` stitches panels into one labeled figure
- `sweep` — the same figure across a parameter grid, ranked by a quality proxy score
- `orchestrate` — parse a full paper, plan multiple method figures + data plots, emit a `figure_package.json` + `figures.tex` bundle

For one or two figures, single-shot `generate`/`plot` stays simpler and cheaper.

### Step 7: Expose it to agents only when a script is not the point

Use the MCP server (11 tools: `generate_diagram`, `generate_plot`, `continue_run`, `evaluate_diagram`,
`orchestrate_figures`, `batch_diagrams`, `batch_plots`, `download_references`, …) or the bundled Claude
Code skills (`/generate-diagram`, `/generate-plot`, `/evaluate-diagram`) when the goal is agent/IDE
access rather than a bespoke run.

bash
bash scripts/run-mcp.sh   # stdio MCP server via uvx --from paperbanana[mcp]


## Examples

### Example 1: The user has a CSV and wants a chart
Use `plot` (or `plot-batch`) — it renders matplotlib from a VLM and needs no image-gen key, so it is the cheapest path.

### Example 2: The user has one method paragraph and wants a diagram
Use `generate` with a clear `--caption`; add `--optimize`/`--auto` only if the first pass underdelivers.

### Example 3: The user already has a figure that is "almost right"
Use `polish` (guided edit) or `evaluate` (judge), not a fresh `generate` run.

### Example 4: The user wants every figure in a paper regenerated
Use `orchestrate` on the paper source; inspect `orchestration_plan.json` with `--dry-run` before spending credits.

### Example 5: The user wants an agent to make figures on demand
Expose the MCP server or the Claude Code skills instead of hand-writing a one-off script.

### Example 6: The figure is a trivial two-bar chart or exact vector art
Route out to plain matplotlib, TikZ, or a vector editor — a multi-agent generative run is overkill or the wrong tool.

## Best practices

1. Start with the smallest mode (`plot` < `generate` < `batch`/`sweep`/`orchestrate`) and escalate only on evidence.
2. Prefer `plot` for data — it skips the image-gen provider entirely and costs less.
3. Fix existing figures with `polish`/`evaluate` before paying for a full regeneration.
4. Treat `--optimize`, `--auto`, `--iterations`, and `--num-candidates` as cost dials — raise them only when a plain run falls short.
5. Pick the cheapest provider that meets quality (Gemini/Atlas VLMs are low cost); the pipeline is provider-agnostic.
6. Use venue style packs (`neurips`, `icml`, `acl`, `ieee`, or a custom pack) instead of hand-tuning aesthetics per run.
7. Judge with the VLM-as-Judge `evaluate` command before claiming a figure is publication-ready.
8. Route out honestly to matplotlib/TikZ/vector editors or a human designer when generative figures are the wrong tool.

## References

- [references/intake-and-route-outs.md](references/intake-and-route-outs.md)
- [references/pipeline-and-agents.md](references/pipeline-and-agents.md)
- [references/modes-and-cli.md](references/modes-and-cli.md)
- [references/providers-and-config.md](references/providers-and-config.md)
- [references/evaluation-and-venues.md](references/evaluation-and-venues.md)
- [scripts/install.sh](scripts/install.sh)
- [scripts/run.sh](scripts/run.sh)
- [scripts/run-mcp.sh](scripts/run-mcp.sh)
- [PaperBanana GitHub Repository](https://github.com/llmsresearch/paperbanana)
- [PaperBanana paper (arXiv:2601.23265)](https://arxiv.org/abs/2601.23265)

© akillness · MIT · akillness/jeo-skills

Similar skills

All skills for Science and research →

From the same set99

The whole set →
okf okf writes and validates Google Open Knowledge Format v0.1 bundles — a folder of Markdown atoms with YAML frontmatter any agent can read. CX Codex +1 127installs agentic-skills agentic-skills runs a task through six gated phases, from spec to ship, and keeps code from starting before the requirements are frozen. CX Codex +1 125installs x-twitter-scraper The x-twitter-scraper skill accesses X data through Xquik for post search, user lookups, media retrieval, monitoring, and approval-based account actions. CX Codex +1 124installs deep-research deep-research turns a topic into an extendable outline, sends parallel agents through each item, then writes a markdown report. Built for comparing a set of things across shared fields. CX Codex +1 120installs webtoon-harness The webtoon-harness skill takes a webtoon episode from trend research through panel creation to a vertical-scroll viewer. Use it to coordinate a full episode workflow. CX Codex +1 115installs opencut A skill for Claude Code guides work on the OpenCut video editor repository. It activates for local setup, Rust/WASM core questions, and contribution planning. CX Codex +1 114installs devup-ui Sets up Devup UI zero-runtime CSS-in-JS in React applications, connects build plugins, and guides migrations away from runtime styling engines. CX Codex +1 111installs gbro-collage-broll The gbro-collage-broll Claude Code skill turns a short voiceover or abstract idea into a vertical paper-collage video. It pauses for approval of the visual concept and still frame before rendering. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open