siril9/presentation-skill / plugins/presentation-skill/skills/presentation-skill
presentation-skill
FlaggedBuild, edit, redesign, render, and verify content-led, structurally diverse, clean, editable, reproducible PowerPoint `.pptx` decks. Use for scientific, lab, clinical, consulting, board, investor, editorial, policy, and operational presentations where alignment, readability, contrast, and balanced density matter.
references/reference_script_patterns.md
View on GitHub# Reference Script Patterns
Patterns distilled from one-off PPTX, DOCX, and figure-generation scripts that
produced stronger decks than generic slide builders. Treat these as product
requirements for the skill, not as code to copy directly.
## Main Finding
The strongest scripts did not win because they had more decorative layouts.
They won because they modeled the work as a report artifact:
- tokenized design constants before any slide logic
- content stored separately from rendering logic
- evidence objects placed first, with text explaining the evidence
- tables and figures styled semantically, not cosmetically
- repeatable figure generation before deck assembly
- visual QA and geometry checks after rendering
For scientific and lab decks, this means the picker should route by evidence
type and presentation posture, not by a static keyword list.
## Portable PPTX Patterns
### Tokenized Design DNA
Reference scripts define slide size, margins, palette, typography, source-line
treatment, and footer position once, then derive each layout from those tokens.
This keeps alignment disciplined and makes topic-specific visual language
portable.
Port into the skill as:
- stronger `design_brief.json` defaults for design DNA
- preset treatments that constrain headers, footers, title layouts, and card
policy
- renderer helpers that use named safe areas instead of ad hoc coordinates
### Content/Render Separation
The better JS decks keep thesis, metadata, and slide arrays outside the
renderer. The renderer is a deterministic layout engine; content files carry
the story.
The skill already has this shape through `content_plan.json`, `evidence_plan.json`,
`asset_plan.json`, and `outline.json`. Preserve that separation. Do not regress
to inline deck-building scripts for normal deck generation.
### Evidence-First Lab Composition
Lab decks repeatedly use:
- one large plot/image panel plus a compact interpretation sidebar
- figure grid plus adjacent metric/codon/result table
- full-width bottom interpretation strip
- concise run metadata in subtitles or captions
- semantic red/green/blue/orange states for genotype, resistance, pass/fail,
concordance, or caveat status
This maps directly to `scientific-figure`, `image-sidebar`,
`lab-run-results`, `table`, and `comparison-2col`. Generic cards should be a
fallback only when the content is truly conceptual or modular.
### Evidence Motif Continuity
Strong lab decks often introduce a small evidence system on the cover: labels
such as Evidence, Readout, Next run; assay stages; or validation checkpoints.
Those labels must not be one-off decoration. If a title slide shows evidence
chips, carry the same system forward as:
- subtitle eyebrows (`EVIDENCE | LOD and concordance`)
- sidebar section labels (`READOUT`, `CAVEAT`, `NEXT RUN`)
- table group titles (`READOUT: Run summary`)
- footer/source prefixes on evidence-bearing slides
- section strips when the deck changes from evidence to action
Encode this in `design_brief.json` as `evidence_continuity` before writing
`outline.json`. Do not create a motif on slide 1 unless the outline has a
clear plan for where it appears again.
### Rich Text Segments
Scientific bullets often need mixed styling inside one line: bold analyte names,
italic gene names, colored result states, units, symbols, and caveats. The
one-off scripts solved this with helper functions that add runs from segment
tuples.
Renderer implication: keep rich text support in helpers and table cells. Do not
force scientific bullets into plain strings when semantic emphasis matters.
### Semantic Tables
The best tables use editable PowerPoint tables, not screenshots, with:
- dark header cells
- alternating row fills
- compact margins
- centered metric values and left-aligned labels
- cell-level highlight styles for calls, mutation rows, borderline states,
discordance, and footnotes
This validates the existing `cell_styles` field and argues for expanding
documented table presets around lab semantics.
### Data-Derived Figure Manifests
The strongest scientific decks generate figures first from local data scripts,
then insert stable output filenames into the deck. Those figure scripts encode
data inputs, output names, labels, color choices, and annotation logic.
Add or emulate a figure manifest when data provenance matters:
```json
{
"figures": [
{
"id": "fig_assay_kinetics",
"script": "scripts/make_figures.py",
"inputs": ["data/run_summary.csv"],
"outputs": ["assets/fig_assay_kinetics.png"],
"caption": "Resistance call kinetics by sequencing time",
"rerun_command": "python3 scripts/make_figures.py"
}
]
}
```
This belongs beside `asset_plan.json`, not buried in speaker notes.
### Slide-Ready Figure Export Contract
Most "tiny image with lots of white space" failures are caused before PPTX
rendering. A renderer can contain-fit an image, but it cannot know which
interior whitespace in a chart is meaningful. When a Python script generates
figures, make it export slide-ready assets:
- choose the plot aspect ratio for the target layout, not for a paper page
- keep legends inside the axes only in a clear region, with space from every
trace and point; otherwise reserve an outside legend row
- use `bbox_inches="tight"` and small `pad_inches` for Matplotlib exports
- run `scripts/trim_image_whitespace.py` on generated PNG/JPG files when the
plot still carries exterior borders
- export one dominant plot for `image-sidebar` when a three-panel
`scientific-figure` grid would make labels or curves unreadable
- store output paths, target variants, target box sizes, and crop rules in
`design_brief.json` under `figure_export_contract`
Check typography at the inserted size, not just in the exported image.
Approximate effective point size as `source_font_pt * inserted_height /
exported_figure_height`, using consistent units for both heights. Target at
least 13 pt for axes, ticks and legends and 9 pt for source metadata. For a
cropped raster, use actual PNG height in pixels divided by export DPI, not the
uncropped figure canvas height. Leave about 10% label-size headroom before
insertion, then recheck the final picture transform and render; increasing DPI
alone does not make labels larger.
Long rotated labels can clip when a tight export reruns layout. Use a horizontal
y-axis label above the plot or enlarge the source canvas, then inspect the PNG
edges and recompute effective label sizes after cropping.
For manual outside labels in Matplotlib, solve layout before saving and include
those labels in `bbox_extra_artists`; changing rotation alone can still clip them.
Example Matplotlib helper for workspace scripts:
```python
def save_slide_figure(fig, path, *, dpi=180):
fig.savefig(path, dpi=dpi, bbox_inches="tight", pad_inches=0.04, facecolor="white")
plt.close(fig)
```
Then trim if needed:
```bash
python3 scripts/trim_image_whitespace.py \
decks/my-deck/assets/figures/*.png \
--in-place --padding 10 --tolerance 12
```
Use Python for deterministic data analysis, inspection, QA, and safe deck
surgery. Do not write a one-off inline
`python-pptx` deck builder for normal generation; it bypasses the layout
measurement and QA pipeline. The efficient pattern is Python for deterministic
data analysis and figure preparation, then `outline.json` plus the fast
`pptxgenjs` renderer for normal editable PowerPoint assembly. Use the Python
renderer only for legacy or renderer-specific behavior the fast path does not
cover.
### Editable Workflow Strips
The strongest process slides use native editable shapes: equal-width rounded
boxes, explicit gap constants, arrow connectors, grouped-stage brackets,
short detail labels, and a final turnaround/result callout.
Use `variant: flow` with 2-4 ordered `flow_steps` objects containing `title`
and optional `detail`. `flow_layout: auto` chooses an equal-height strip or
readable stacked bands; `strip` and `bands` are bounded explicit choices.
All stage text and connectors remain editable. A longer method must be split,
not silently truncated. Do not supply both steps and a Mermaid/diagram asset.
Mermaid remains useful for graph-shaped diagrams rather than simple methods.
### Measured Evidence Regions
Reserve the complete interpretation and source caption before allocating plot
space. Modern scientific layouts retain each panel caption in `panel-grid`,
`primary-rail`, `ledger-rail`, and `strip-readout`; explicit v1 workspaces keep
their original rendering. `figure_frame: open | ruled | panel` controls framing,
not plot geometry. A restrained heading/footer can stay consistent while the
evidence changes between a large plot, panel pair, measured ledger, native
table, and methods strip. When labels inside a bitmap are too small, regenerate
the figure for the actual slide region. The renderer cannot enlarge plot labels
independently of the data.
### Safe Incremental Deck Surgery
When editing existing decks, the useful pattern is:
- copy or back up before mutation
- find slides by known text
- remove only selected shapes
- preserve existing image boxes when swapping figures
- reinsert assets at the same geometry
- renumber after slide insertion/reordering
- inspect shape positions before edits
This belongs in editing tooling and references. It should not replace the
workspace rebuild flow when source files are available.
### Deck Inspection Dump
A small inspection script that prints slide size, layout name, shape type,
position, text, and table contents is disproportionately useful before editing
an existing deck. It turns visual guesswork into measurable geometry.
The skill should keep an inspection path available for template adaptation and
incremental edits.
## Portable DOCX Patterns
DOCX scripts showed the same pattern as good decks: define styles once, then
compose structured content. Reusable ideas:
- markdown-ish rich text parsing for `**bold**` spans
- centered title/subtitle handling
- section heading helpers with bottom borders
- bullet style normalization with hanging indents
- compact key-value tables
- highlighted "needs input" fields for forms
- metadata cleanup before delivery
- LibreOffice PDF export for layout inspection
If the presentation skill later adds speaker handouts or companion reports,
reuse these document primitives rather than generating raw paragraphs.
## Dynamic Style/Content Routing
Do not implement lab routing as only:
```text
if prompt contains ASCO/TB/LAMP/clinical/LOD/sequencing/assay/sample/resistance:
use lab-report
```
Those terms are useful priors, but static token matching fails in both
directions. A public health explainer can mention TB and still need an editorial
policy deck. A lab deck can omit those exact tokens and still require figures,
tables, captions, and source lines.
Use a deck-level style/content scout when the task is non-trivial, researched,
scientific, or asset-heavy. The scout should classify:
- user objective: talk, report, leave-behind, pitch, poster, lab update
- audience posture: scientific peer, clinician, executive, public, student
- evidence objects: plots, microscopy/images, assay readouts, result tables,
raw data, workflow, screenshots, citations, metrics
- proof burden: exploratory concept, sourced report, clinical/lab claim,
regulatory or validation claim
- asset availability: local figures, generated figures, source-backed images,
tables, charts, no assets yet
- density: live talk, readable report, dense leave-behind
- bounded design modulation: subtle/moderate/bold shift, accent role,
whitespace, density, motif, container policy, and figure/table treatment
Then choose:
- `style_preset`
- `deck_style` treatments such as `header_mode`, `footer_mode`, and
`research_visual_mode`
- `design_modulation` so agents can make suitable micro-design changes without
inventing unsupported inline colors or fonts
- allowed and forbidden variants
- slide-level routes from role/evidence to variant
- asset requests and figure/table provenance needs
- QA sensitivities
and whether content research or data/evidence analysis subagents are needed
For lab/report evidence, the expected route is usually:
- preset: `lab-report` or another restrained report preset
- style: `header_mode: lab-clean`, `footer_mode: source-line`,
`summary_callout_mode: lab-box`, `research_visual_mode: true`
- variants: `scientific-figure`, `image-sidebar`, `lab-run-results`, `table`,
`comparison-2col`, and carefully scoped `flow`
- avoid: generic `cards-3`, decorative icon grids, forced KPI hero slides, and
process diagrams that do not carry evidence
For brand/product/editorial decks, use the same scout but pick a different
design DNA. The scout is not a lab-only feature; it prevents all deck types from
collapsing into generic cards.
## Recommended Implementation Order
1. Keep the pattern report and scout prompt in the repo so agents have a shared
method to follow.
2. Add a prompt emitter for one deck-level style/content scout before outline
finalization.
3. Add planning validation that warns when lab DNA uses mostly generic cards or
when product/editorial DNA forces lab/report layouts without evidence.
4. Keep hardening the figure-manifest convention for data-derived scientific
figures; `scripts/scaffold_figure_artifacts.py` now creates the first
deterministic `assets/make_figures.py`, chart JSON, slide-ready figure, and
artifact-plan draft from simple tabular data.
5. Use the native method strip and measured evidence regions before adding more
decorative layouts.
6. Add an inspection command for existing PPTX geometry and tables.
7. Expand regression fixtures around `scientific-figure`, `image-sidebar`,
`lab-run-results`, and semantic table cell styles.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |