Add Figure Skill

This skill adds a new runtime skill at

container/skills/figure/

for publication-quality plotting inside BioClaw containers.

What This Adds

• A new container runtime skill:

  container/skills/figure/SKILL.md

• A flattened seaborn reference:

  container/skills/figure/seaborn_reference.md

• Python-only plotting guidance for

  matplotlib

  ,

  seaborn

  ,

  scanpy

  , and related Python tools
• Journal palette constants translated to Python hex lists and dicts

What This Must Not Change

• Do not modify any source files in

  src/

  ,

  container/agent-runner/

  , or other app code
• Do not modify

  Dockerfile

• Do not modify sync logic in

  src/container-runner.ts

• Do not add any R dependency or R code examples

The feature is entirely delivered as a skill, not as application code.

Why This Shape

BioClaw already syncs

container/skills/<skill>/

into

/home/node/.claude/skills/<skill>/

inside the container.

The sync only copies one directory level, so any reference material needed at runtime must live directly under

container/skills/figure/

, not under nested

references/

.

Implementation Steps

Run all steps directly. Only pause if the repo already contains a user-modified

container/skills/figure/

and you need conflict resolution.

1. Verify Current State

Check:

pwd
ls -la container/skills
test -e container/skills/figure && echo "figure skill already exists" || echo "no figure skill yet"

If

container/skills/figure/

already exists, inspect it before changing anything.

2. Create

container/skills/figure/

Create:

container/skills/figure/
├── SKILL.md
└── seaborn_reference.md

Do not add nested directories.

3. Write

container/skills/figure/SKILL.md

Create a Python-only runtime skill with frontmatter like:

---
name: figure
description: Python-only reference for publication-quality academic figures inside BioClaw containers. Covers matplotlib, seaborn, scanpy-style workflows, journal palette constants, bioinformatics plot standards, anti-patterns, and a pre-flight quality checklist.
---

The file must include all of the following sections.

Required Section: Purpose and Rules

State clearly:

• Python only
• Save outputs to

  /workspace/group/

• Prefer

  .pdf

  or

  .svg

  for final figures
• Use

  .png

  only when raster is necessary, at

  dpi >= 300

• Root-level seaborn reference lives at

  /home/node/.claude/skills/figure/seaborn_reference.md

Required Section: Tool Routing

Include a short table routing these tasks to Python tools:

• General plots ->

  seaborn

  +

  matplotlib

• Annotation-heavy custom figures ->

  matplotlib

• Single-cell embeddings ->

  scanpy

• Clustered heatmaps ->

  seaborn.clustermap

• Set intersections ->

  upsetplot

• Survival curves ->

  lifelines

  +

  matplotlib

• Enrichment bubble plots ->

  seaborn.scatterplot

Required Section: Chart Type Selection

Include a Python-only chart selection table for:

• Histogram / density / violin
• Group comparison
• Scatter / hexbin
• Line / area
• Heatmap / clustered heatmap
• Volcano plot
• UMAP / t-SNE
• Relative composition
• Alpha diversity
• Beta diversity / ordination
• Enrichment bubble plot
• Kaplan-Meier curve
• Multi-panel layout

Every row must reference Python functions only.

Required Section: Publication-Quality Defaults

Include a code block defining:

• BIO_STYLE

• SAVEFIG_KWARGS

• finish_axis(ax)

The style must:

• Use sans-serif fonts with Arial/Helvetica fallbacks
• Remove top and right spines
• Set figure and save DPI to 300
• Set

  savefig.bbox

  to

  tight

• Keep visible text at publication-safe sizes
• Preserve editable SVG text with

  svg.fonttype = "none"

Required Section: Universal Standards

Document:

• Vector first
• Raster at 300+ DPI
• No on-image title
• Labeled axes with units
• Legend placement
• Panel labels for multi-panel figures
• Tight margins
• Minimum text size

Required Section: Color Standards

Include:

• Discrete palette usage guidance
• Continuous palette usage guidance
• Colorblind and consistency rules
• Explicit ban on

  jet

  and

  rainbow

Required Code Block: Python Palette Constants

Define a

JOURNAL_PALETTES

dict containing these keys:

• NPG

• Lancet

• AAAS

• JCO

• NEJM

• D3_CATEGORY10

• D3_CATEGORY20

Define a

MATERIAL_PALETTES

dict containing named color families such as:

• red

• pink

• purple

• deep_purple

• indigo

• blue

• light_blue

• cyan

• teal

• green

• light_green

• lime

• yellow

• amber

• orange

• deep_orange

• brown

• gray

• blue_gray

Also define:

def apply_palette(name, n=None):
    colors = JOURNAL_PALETTES[name]
    return colors if n is None else colors[:n]

Use these exact journal palette hex values:

JOURNAL_PALETTES = {
    "NPG": [
        "#E64B35", "#4DBBD5", "#00A087", "#3C5488", "#F39B7F",
        "#8491B4", "#91D1C2", "#DC0000", "#7E6148", "#B09C85",
    ],
    "Lancet": [
        "#00468B", "#ED0000", "#42B540", "#0099B4",
        "#925E9F", "#FDAF91", "#AD002A", "#ADB6B6",
    ],
    "AAAS": [
        "#3B4992", "#EE0000", "#008B45", "#631879", "#008280",
        "#BB0021", "#5F559B", "#A20056", "#808180", "#1B1919",
    ],
    "JCO": [
        "#0073C2", "#EFC000", "#868686", "#CD534C", "#7AA6DC",
        "#003C67", "#8F7700", "#3B3B3B", "#A73030", "#4A6990",
    ],
    "NEJM": [
        "#BC3C29", "#0072B5", "#E18727", "#20854E",
        "#7876B1", "#6F99AD", "#FFDC91", "#EE4C97",
    ],
    "D3_CATEGORY10": [
        "#1F77B4", "#FF7F0E", "#2CA02C", "#D62728", "#9467BD",
        "#8C564B", "#E377C2", "#7F7F7F", "#BCBD22", "#17BECF",
    ],
    "D3_CATEGORY20": [
        "#1F77B4", "#AEC7E8", "#FF7F0E", "#FFBB78", "#2CA02C",
        "#98DF8A", "#D62728", "#FF9896", "#9467BD", "#C5B0D5",
        "#8C564B", "#C49C94", "#E377C2", "#F7B6D2", "#7F7F7F",
        "#C7C7C7", "#BCBD22", "#DBDB8D", "#17BECF", "#9EDAE5",
    ],
}

Translate the Material palette into Python hex lists under

MATERIAL_PALETTES

. Keep it as a dict of family name -> 10-step tonal list.

Required Section: Bioinformatics-Specific Plot Standards

Include Python examples and standards for:

• UMAP / t-SNE
• Heatmap
• Volcano plot
• Relative composition bar plot
• Alpha diversity
• Beta diversity / ordination
• Enrichment bubble plot
• Survival curve

The examples must use Python syntax only.

The section must explicitly require:

• UMAP/t-SNE axes without ticks
• Heatmaps with visible color bars
• Volcano plots with cutoff lines at

  abs(log2FC) >= 1

  and

  padj <= 0.05

• Relative abundance y-axis constrained appropriately
• Alpha diversity shown with both summary and individual points
• PCoA axes labeled with explained variance when available
• Survival plots labeled with time unit

Required Section: Quality Checklist

Include a pre-flight checklist covering:

• Output format / DPI
• Axis labels and units
• No in-figure title
• Legend placement
• Panel labels
• Color consistency
• Colorblind-safe interpretation
• Statistical annotation correctness
• Minimum font size
• No chartjunk

Required Section: Anti-Patterns

Include a table forbidding at least:

• Default unstyled plots
• Too many cluster colors in one panel
• UMAP/t-SNE with ticks
• Heatmap without labeled color bar
• Volcano plot without thresholds
• Bar plots that hide variability
• Overlapping labels

Required Section: Working Rules

End with rules such as:

• Prefer reusable plotting code over one-off snippets
• Keep filenames stable and descriptive
• Keep figure code reproducible in the workspace
• Fall back to plain

  matplotlib

  if a preferred library is unavailable

4. Write

container/skills/figure/seaborn_reference.md

Create a root-level seaborn reference file for shallow-copy sync. It should be concise but directly usable.

It must include:

• Title:

  # Seaborn API Reference

• Source note pointing to https://seaborn.pydata.org/
• Objects interface example using

  seaborn.objects as so

• Short tables for marks and stats
• Sections for:
  • Relational plots
  • Distribution plots
  • Categorical plots
  • Regression plots
  • Matrix plots
  • Multi-plot grids
  • Style and context
• A final

  ## Common Patterns for Bio

  section with examples for:
  • Volcano plot
  • Expression heatmap with clustering
  • Violin + strip
  • UMAP embedding

Keep the file at the skill root. Do not place it under

references/

.

5. Explicit Removals and Exclusions

The generated

container/skills/figure/SKILL.md

must not contain:

• AutoFigure-Edit

• ggplot2

• ComplexHeatmap

• clusterProfiler

• BioCircos

• circlize

• R Graph Gallery

• r4ds

• Any

  geom_

  examples
• Any R code fences

This skill is intentionally Python-only because the BioClaw container does not include R.

6. Validation

Run:

ls -la container/skills/figure

rg -n "AutoFigure|ggplot2|ComplexHeatmap|clusterProfiler|BioCircos|circlize|R Graph Gallery|r4ds|geom_" \
  container/skills/figure

rg -n "JOURNAL_PALETTES|MATERIAL_PALETTES|NPG|Lancet|AAAS|JCO|NEJM|D3_CATEGORY10|D3_CATEGORY20" \
  container/skills/figure/SKILL.md

If Docker is available, also verify in-container readability:

docker run --rm --entrypoint sh \
  -v "$PWD/container/skills/figure:/home/node/.claude/skills/figure:ro" \
  bioclaw-agent:latest \
  -lc 'ls -1 /home/node/.claude/skills/figure && sed -n "1,10p" /home/node/.claude/skills/figure/SKILL.md'

7. Final Output to the User

Report:

• Which files were created
• That no source files were modified
• That the skill is Python-only
• Validation results

If preparing for a PR, remind the user that the PR should only include the new contributed skill under

.claude/skills/add-figure/

when contributing back to the BioClaw repo.