Paper Figure

Describe the figure. Refine a preview. Say “use this”. Get editable SVG, PDF and PPTX.

Paper Figure is a small Codex skill backed by local build tools. It keeps design, confirmation and reconstruction in one conversation, without asking you to fill forms, move files between chats, or configure a separate image API.

v2.1.1 · Preview release. Local export, state and safety checks are tested. Native Codex image generation and arbitrary scientific-figure reconstruction are not covered by these automated tests. A host image tool is required for generated concepts; this skill cannot grant a tool the client does not provide.

This project focuses on repeatable revisions and same-source delivery. It is not a claim of a unique drawing method or superior figure quality. See related work.

Use it

In a Codex conversation with the skill installed:

$paper-figure Create a method overview: short video → geometry prediction →
future spatial answers. Keep the scientific labels editable. Show me a concept first.

The explicit skill name is useful at the start; it is not required in every message. Then speak normally:

Make the right panel less crowded. Keep the furniture unchanged.
Use v2. Rebuild it.
Change “Prediction” to “Geometry Encoder”; keep everything else unchanged.

A supplied, already-approved image can go directly to reconstruction. Simple block diagrams can start as native drafts rather than spend an image generation. Image edits stay on the selected version. After reconstruction, label/layout changes edit native objects—not a regenerated full image.

Install once

Give Codex the published skill URL:

$skill-installer https://github.com/GuangSTrip/paper-figure/tree/main/skills/paper-figure

Or, from a reviewed local checkout:

python3 install.py --replace --with-deps

--replace backs up any previous installation. --with-deps explicitly authorizes pip downloads into a private runtime under ~/.cache/paper-figure/2.1.0/venv. It does not change global Python, Codex config or account credentials. This local installer defaults to ~/.agents/skills/paper-figure/; Codex skill-installer may use ~/.codex/skills/paper-figure/. Update the existing location with --target instead of creating a second installation. Refresh skill discovery if needed.

System requirement: Python 3.10+. PDF export also needs Inkscape. On macOS:

brew install --cask inkscape

LibreOffice is optional for PPTX previews; otherwise review the PPTX in PowerPoint. On macOS, restricted execution can abort Inkscape before export; see renderer troubleshooting. For Ubuntu, project-local installation and manual dependency setup, see installation. Install on the machine where Codex actually runs.

What is actually implemented?

Component	Implementation
Concept generation/editing	Host Codex image tool; capability-checked instructions, not a hidden API client
Version history	Immutable local image copies, parent IDs, notes, hashes and current selection
Approval	Pins a version/hash; a new concept invalidates approval; managed exports enforce this
Local revision	Stable-ID patching; checkpoints detect out-of-scope native/asset changes
Comparison	Side-by-side and pixel-difference previews; not a semantic similarity score
Export	Common scene → native SVG/PPTX; Inkscape → PDF; independent raster assets
Checks	Native text/geometry, labels, fonts, raster DPI, screenshot wrapping, stale files
Publication	Offline-reviewed snapshot → authenticated GitHub CLI → new public repo and prerelease

Synthetic native figure example

The example is a synthetic software fixture, not a real experiment, recorded video or proof of image-model reconstruction quality. SVG · PDF · PPTX

Why not just a prompt?

The model owns design and scientific interpretation. The skill owns workflow routing. Scripts own repeatable export and checks. Deleting the skill does not make a model unable to draw; it removes the reusable state, approval and build infrastructure. There is one skills/paper-figure/ source tree, not mirrored copies.

Intent → selected concept → user approval → scene + independent assets
                                             ↓
                                  SVG + PDF + native PPTX
                                             ↓
                                machine checks + actual review

The user supplies intent and feedback. Codex maintains brief.json, native scene, concept history and QA records internally. Architecture

Boundaries that matter

The built-in scene supports groups, ordinary text, common shapes, straight connectors, polygons/polylines and PNG/JPEG assets. It is not a general SVG-to-PPTX converter. Complex formulas, arbitrary paths, native charts and advanced gradients need an explicit custom source/backend, not silent flattening.

PDF is a submission export; SVG and PPTX retain native objects. Fonts must be available to an editor. Raster assets remain resolution-limited. PowerPoint edits do not automatically sync back; the exporter protects edited outputs from unacknowledged replacement. Machine checks do not certify scientific correctness, accessibility, exact renderer parity, or conference compliance.

No browser-cookie access, implicit paid API fallback, telemetry or public preview server is bundled. Host model calls still follow that provider's policies/usage limits. Privacy · Security

Develop and share

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
python scripts/validate_repo.py
python -m unittest discover -s tests -v
python scripts/package.py --refresh-manifest

The root plugin.json uses the portable Agent Plugins format. The compatibility manifest .codex-plugin/plugin.json references the same skill tree. Local marketplace metadata is included for supported Codex clients. Public-directory review is separate from a GitHub release; this project does not claim a listing or official verification. Publishing

Research and implementation decisions are documented in references. Contributions: guide · live-evaluation plan.

MIT for project code; third-party dependencies retain their licenses. No font files are distributed. See third-party notices.