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/.
1---
2name: publication-chart-skill
3description: 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.
4version: 0.2.0
5metadata:
6 source: https://skillmd.com/skills/gabrielmoreira/publication-chart-skill
7---
8
9# Publication Chart Skill
10
11## Goal
12
13Use this skill to turn research results into **publication-grade figures and tables** with an end-to-end workflow.
14
15Primary production stack:
16
17- **`pubfig`** for figures
18- **`pubtab`** for publication tables
19
20This skill covers the full delivery chain:
21
221. understand the scientific communication goal,
232. choose the right artifact type,
243. map the task to `pubfig`, `pubtab`, or both,
254. generate concrete runnable instructions,
265. export paper-ready assets,
276. run publication QA,
287. propose targeted revisions.
29
30## Use this skill when
31
32Trigger this skill for requests like:
33
34- “make a publication-quality figure”
35- “choose the right chart for these results”
36- “turn these results into a paper-ready figure”
37- “make a benchmark / ablation / calibration / forest / heatmap / scatter / line / bar figure”
38- “make a benchmark / appendix / ablation table from Excel”
39- “convert this Excel table into publication-ready LaTeX”
40- “prepare one summary figure plus one companion table for the results section”
41- “review and improve this scientific figure/table”
42- “I already have a weak chart / screenshot / draft plot — make it publication-ready”
43- “export panels for a paper figure”
44
45## Do not use this skill for
46
47Do **not** use this skill when the task is mainly:
48
49- manuscript prose writing,
50- statistical testing without artifact design,
51- raw exploratory analysis with no publication deliverable,
52- Figma-first layout work before the figure/table content is solid.
53
54For simple composite assembly after the figure content is already strong, use the optional secondary workflow in `references/composite-assembly.md`.
55
56## Primary contract
57
58### Inputs
59
60Expect some combination of:
61
62- the scientific communication goal,
63- available data shape,
64- venue or style constraints,
65- whether the artifact is a figure, table, or mixed deliverable,
66- optional existing assets such as code, spreadsheets, `.tex`, screenshots, or draft plots,
67- whether the user needs a first draft, a publication-ready artifact, or a review/revision pass.
68
69### Outputs
70
71The minimum useful output is:
72
73- the recommended figure/table form,
74- the recommended `pubfig` / `pubtab` route,
75- a minimal runnable code snippet or CLI command,
76- explicit export filenames and formats,
77- a publication QA summary,
78- and, when needed, a revision plan.
79
80## Default workflow
81
82### 0. Probe the environment and artifact state
83
84Before generating anything, identify:
85
86- whether `pubfig` or `pubtab` is actually available,
87- whether the user already has code / spreadsheets / `.tex` / screenshots,
88- whether the deliverable is a fresh build or a revision,
89- whether the result needs exact values, fast visual perception, or both.
90
91Prefer the smallest environment check that helps execution. When the bundled helper script is available, use it first:
92
93- `python3 scripts/ensure_publication_tooling.py --require pubfig --json`
94- `python3 scripts/ensure_publication_tooling.py --require pubtab --json`
95
96Equivalent manual checks are still acceptable when needed:
97
98- `python -c "import pubfig; print(pubfig.__version__)"`
99- `python -c "import pubtab; print(pubtab.__version__)"`
100- `pubtab --help`
101
102Report the result clearly as **available** or **missing**.
103
104If a dependency is missing and the task requires runnable execution:
105
106- **auto-install it by default**,
107- prefer the user’s active environment instead of guessing a random global interpreter,
108- use `python3 scripts/ensure_publication_tooling.py --require ...` as the default bundled route when the script is present,
109- let that helper choose `uv` vs `python -m pip` against the active interpreter,
110- re-run the availability probe after installation,
111- and only then continue with the artifact workflow.
112
113Equivalent concrete commands include:
114
115- `python3 scripts/ensure_publication_tooling.py --require pubfig`
116- `python3 scripts/ensure_publication_tooling.py --require pubtab`
117- `uv pip install pubfig`
118- `uv pip install pubtab`
119- `python -m pip install pubfig`
120- `python -m pip install pubtab`
121
122If auto-install fails, report the exact failure and then degrade gracefully.
123
124Do not block on a full environment audit.
125
126### 1. Classify the task
127
128Classify the request along these axes:
129
130- **artifact type**: figure / table / mixed deliverable
131- **maturity**: exploratory draft / publication-ready generation / revision of an existing artifact
132- **structure**: single panel / multi-panel / figure-plus-table package
133- **evidence mode**: pattern perception / exact value lookup / both
134
135Do not jump into plotting code before the communication target is clear.
136
137Before plotting research results, lock the evidence contract:
138- primary scientific claim,
139- unit of analysis,
140- primary metric and metric direction,
141- whether repeated rows are independent,
142- missing cells or incomplete comparison blocks,
143- error-bar basis: subject, subject-task, fold, seed, run, or bootstrap sample,
144- whether exact values need a companion table,
145- whether the current evidence allows a winner/significance claim.
146
147If 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.
148
149### 2. Choose the representation
150
151Choose the representation based on the scientific claim, not novelty or visual flair.
152
153Common families:
154
155- **comparison** — grouped scatter, bar, line comparison, benchmark summary, companion table
156- **ablation** — grouped comparison, dumbbell, paired comparison, compact table
157- **distribution** — box, violin, raincloud, histogram, density, ECDF, QQ
158- **relationship** — scatter, bubble, contour2d, hexbin
159- **trend** — line, area
160- **evaluation / diagnostic** — calibration, ROC, PR, Bland–Altman, forest plot, volcano
161- **composition / hierarchy** — UpSet, stacked ratio, donut, radial hierarchy, circular grouped or stacked bars
162- **table** — benchmark table, ablation table, dataset summary, appendix table, error breakdown
163
164Avoid weak defaults:
165
166- avoid pie/donut when exact comparison matters and a bar/table is clearer,
167- avoid radar unless the comparison is genuinely profile-like and low-cardinality,
168- avoid 3D, decorative gradients, and dense legends used only for style,
169- avoid forcing every result into a figure when a publication table communicates the evidence better.
170
171If the request is ambiguous, explicitly state what scientific claim the artifact is supposed to support.
172
173### 3. Map to the toolchain
174
175Default mapping:
176
177- **Figures** → `pubfig`
178- **Tables** → `pubtab`
179- **Mixed deliverables** → use both, with each artifact carrying a distinct role
180
181Tool roles:
182
183- `pubfig` is the default figure engine for scientific plots and paper-ready export.
184- `pubtab` is the default table engine for Excel ↔ LaTeX workflows, preview, and publication-ready table export.
185- Figma/composite assembly is an **optional secondary branch** for multi-panel finishing.
186
187Route selection rules:
188
189- prefer **Python** for `pubfig` figure generation,
190- prefer **CLI** for `pubtab` when the task is file-driven,
191- prefer **Python** for `pubtab` when the task is already inside a notebook or scripted pipeline,
192- keep the figure and table responsibilities separate in mixed requests.
193
194### 4. Generate concrete artifact instructions
195
196Prefer the smallest production-ready artifact first:
197
198- minimal runnable Python for `pubfig`, or
199- minimal CLI/Python for `pubtab`
200
201Then add publication parameters only when justified:
202
203- labels, caption, width, export format, backend, preview, panel packaging, or composite layout.
204
205Keep filenames and suffixes explicit.
206
207Good defaults:
208
209- figures: one `pubfig` call + one `save_figure(...)`
210- multiple figure outputs: `batch_export(...)`
211- tables: one `pubtab xlsx2tex ...` or `pubtab.preview ...`
212- mixed requests: one figure route + one table route, clearly separated
213
214### 5. Define the delivery contract
215
216For every response, make these explicit when possible:
217
218- the claim the artifact supports,
219- which part is handled by `pubfig` and which by `pubtab`,
220- the output filenames,
221- the output formats,
222- whether the artifact is draft / final / revision,
223- what still needs user-provided data or manuscript context.
224
225### 6. Run publication QA
226
227After generation, check:
228
229- title and legend density,
230- axis labels and units,
231- category ordering and baseline clarity,
232- color accessibility and grayscale robustness,
233- font / line-weight consistency,
234- caption readiness,
235- figure/table readability after downscaling,
236- panel consistency for multi-panel figures,
237- venue-fit issues such as width, crowding, or over-annotation.
238
239The QA output must be concrete. Do not say “looks better” without naming why.
240
241### 7. Revise
242
243If the result is weak, revise with specific changes such as:
244
245- switch chart family,
246- remove chartjunk,
247- reorder categories,
248- move exact values into a table,
249- split a crowded panel,
250- add or simplify the caption,
251- change export width,
252- or convert the deliverable from figure-first to table-first.
253
254## Missing dependency behavior
255
256If `pubfig` or `pubtab` is not available:
257
258- do **not** fail immediately,
259- first attempt automatic installation into the active environment,
260- prefer `python3 scripts/ensure_publication_tooling.py --require ...` when the bundled script exists,
261- explicitly state which dependency is missing,
262- state which install command or helper route is being used,
263- re-check availability after installation,
264- if installation succeeds, continue with the runnable workflow,
265- if installation fails, degrade to a design/specification workflow,
266- provide pseudocode or draft commands,
267- preserve the recommended figure/table structure,
268- still provide QA and revision guidance.
269
270## Composite assembly rule
271
272Treat composite or Figma assembly as **secondary**:
273
274- use it when the user explicitly wants a multi-panel paper figure,
275- or when panel-level export and layout polishing are genuinely needed.
276
277Do not escalate simple figure tasks into composite/Figma workflows by default.
278
279## Output style rules
280
281- Prefer direct, implementation-usable outputs.
282- Explain the **why** of chart/table choice briefly, then give the runnable route.
283- When execution matters, include a short environment status block such as `pubfig: available/missing`, `pubtab: available/missing`.
284- If a dependency is missing, state the exact helper command or install command, perform the installation, and report the post-install status.
285- When a table is stronger than a figure, say so explicitly.
286- When a figure is stronger than a table, say so explicitly.
287- When both are needed, assign them different communication roles.
288- Keep revision guidance actionable and falsifiable.
289
290## Recommended response shape
291
292A strong response using this skill usually has 6 parts:
293
2941. **Artifact decision** — figure / table / paired deliverable, and why
2952. **Tool route** — `pubfig`, `pubtab`, or both
2963. **Minimal implementation** — runnable code or CLI
2974. **Export plan** — filenames, formats, width/backend/preview choices
2985. **Publication QA** — what to verify before paper submission
2996. **Revision plan** — what to change if the current artifact is weak
300
301## Resources
302
303Load these as needed:
304
305- `references/workflow.md` — full end-to-end decision order and delivery contract
306- `references/chart-selection.md` — task-to-chart mapping and anti-patterns
307- `references/execution-and-verification.md` — environment probing, forced install behavior, and runnable verification
308- `scripts/ensure_publication_tooling.py` — bundled probe + auto-install helper for `pubfig` / `pubtab`
309- `references/pubfig-recipes.md` — shortest useful figure patterns and export routes
310- `references/pubtab-recipes.md` — shortest useful table routes and backend guidance
311- `references/source-guides/pubfig-architecture.md` — package layout and figure-generation boundaries from source
312- `references/source-guides/pubfig-api-map.md` — stable public pubfig surface and chart-family map from `__init__.py`
313- `references/source-guides/pubfig-export-flow.md` — figure export, publication sizing, and panel-export flow from source
314- `references/source-guides/pubtab-architecture.md` — package layout and forward/reverse conversion architecture from source
315- `references/source-guides/pubtab-cli-api-flow.md` — CLI-to-API control flow and batch/sheet behavior from source
316- `references/source-guides/pubtab-backend-and-preview.md` — backend/theme split and real preview compile pipeline from source
317- `references/publication-qa-checklist.md` — figure/table QA checklist
318- `references/composite-assembly.md` — optional multi-panel and Figma branch
319
320For prompt-shaped examples, see `examples/`.