Vivid Figures Skill

What It Does

Vivid Figures (vivid-figures-skill) is a Chinese-language scientific plotting skill for AI assistants that follow the Agent Skills convention, documented primarily for Claude Code. Given CSV, Excel, or JSON data, the agent reads the routing contract in SKILL.md, picks one of 108 chart recipes (grouped bars through ridgeline plots, rainclouds, ROC curves, 3D surfaces, maps), renders PNG plus PDF plus editable plotting source, and self-reviews the rendered image before delivery. The repo is a wrapper: an 18-line SKILL.md routes into original/, which preserves (verbatim, per its own manifest) the plotting capability of the HaJiMi desktop app, itself compiled from an earlier Codex plotting skill. The wrapper adds an Anthropic host adapter, a five-palette color selection layer, install docs, and a Node-based figure-plan validator. The target user is a Chinese-speaking student or researcher producing figures for math-modeling competitions (MCM, ICM, CUMCM) or journal papers.

The Good

The recipe integrity system is the strongest GearScope has tested in a plotting skill. Every one of the 108 recipes carries a contentSha256 in recipe_registry.json, and retrieval (get_recipe.py) works by stable ID (advanced.ridgeline), legacy number (basic 3), or plan reference, refusing anything that does not match. I recomputed all 108 hashes with the registry's own normalization rule: 108 of 108 match. Category split: basic 12, advanced 34, empirical 21, academic 12, competition 29.

The utility library does real QA work, and I watched it fire. plot_utils.py (2,287 lines) lazy-imports matplotlib on Agg, reads palette and style markers from the workspace CLAUDE.md, and hooks savefig to auto-fix label overlaps, warn on wasted margins, and warn when data is clipped. During my functional run it printed a live diagnostic on my test heatmap: WARNING fig_heat.pdf 左边距偏大: 实测 16.8% 图宽，y 标签实际只需 4.6% (left margin 16.8% of figure width where labels need 4.6%), exactly the wasted-space detection it claims. It also ships seeded anti-fingerprint styling so repeated papers do not all look stamped from one template.

The figure-plan validator is genuine enforcement, not decoration. scripts/figure-plan.ts (invoked via node --experimental-strip-types) validates a FIGURE_PLAN.json contract: at least 8 distinct DATA figures, no chart type repeated more than 3 times, one DRAWIO roadmap, a TIKZ derivation figure per reasoning-heavy question, per-question coverage, source files that must exist and must stay inside the workspace (a path-containment check), and a plan-hash pin on acceptance. A valid 9-figure plan I generated passed with "valid": true; a 2-figure plan was rejected with DATA requires at least 8 distinct figures.

The showcase is reproducible and honest. The README's five palette images are generated by a committed script (examples/palette-showcase/render.py) from a committed 1,681-line synthetic CSV, with a render-info.json audit. My re-render produced identical audit content (same colors, same 240 samples per group, same medians to 4 decimals) and identical pixel geometry (1800x1170). Two runs on my machine were byte-identical (coral.png md5 3ee8ac3b...). The committed PNGs differ from my output at the byte level, which traces to font rasterization across environments, not content. The README also states plainly that examples are not a guarantee of every run's output and that the model may not follow the guidance.

Security posture on the data path is clean. Zero network imports in plot_utils, get_recipe, bootstrap, resolve_runtime, or the manifest validator. The only network-capable files are a bibliography DOI checker (doi.org HEAD requests) and a legacy gpt_image.py illustration tool that defaults to a third-party relay (https://www.mhcoding.ai/); the host adapter explicitly maps illustration rendering to the host's own image-generation capability instead, and the data-figure path never touches either file. The 59 encrypted .enc files (1,436 KB) are inert provenance copies from the original encrypted distribution; no executable in the repo references them.

The Bad

The license conflicts with how the skill ecosystem works. The custom "Personal Non-Commercial License" prohibits modification, adaptation, redistribution (beyond a private backup), secondary development, and any commercial use including internal business operations. GitHub reports NOASSERTION. A skill whose distribution norm is git clone, npx skills add, registry mirroring, and organizational rollout sits awkwardly under a no-redistribution, no-commercial clause: forking the repo on GitHub is redistribution, and using it to produce figures for your employer is commercial use. Anyone evaluating this for a company, a lab with funding, or a product should treat it as untouchable without written permission.

Provenance is documented but tangled, and the copyright claim is bold. PROMPT_PROVENANCE.json and upstream-planning.md record that the content came from Windows paths like C:\Users\hhhh\Desktop\try 1\work\original-full-analysis\decrypted-skills\...: a local Codex skill, packaged into the HaJiMi app, later decrypted, now republished. The in-repo manifest honestly marks the original license status as "not-declared-in-source-snapshot". The wrapper author then claims copyright over the whole bundle. The chain is transparent, which deserves credit, but a downstream user cannot tell from the repo alone whether every layer of that chain authorized this publication.

Everything operational is Chinese-only. SKILL.md, all 108 recipes, the style guide (79,783 bytes), the error-prevention manual (130,824 bytes), runtime warnings, and the install docs are Chinese. An agent can still execute the Python, but a non-Chinese-speaking operator cannot audit the guidance their agent is following. This is an ecosystem-fit limitation rather than a craftsmanship one, but it caps the audience hard.

Legacy naming and dead weight leak through the wrapper. The runtime stamps .codex-plot-runtime.json in your workspace, the adapter must override "Claude means Codex" statements baked into the original text, plan state lives under .hajimi/, and the color markers are MH_DATA_FIG_*. The 59 .enc blobs are inert but ship 1.4 MB of unreadable bytes. None of this breaks anything (bootstrap, retrieval, and rendering all worked first try), but it is cognitive overhead the adapter doc has to keep apologizing for.

Install weight and small frictions. requirements.txt lists 21 packages including geopandas, PyMuPDF, and CairoSVG; the data-figure subset alone (numpy, pandas, scipy, matplotlib, seaborn, adjustText) measured 314 MB installed. On macOS, setup_style() selected the STSong font family and matplotlib logged findfont: Failed to find font weight normal for STSong, now using 300 on every render, benign but noisy and undocumented in the troubleshooting table. There are no git tags, no CI, and no self-test suite beyond the showcase script; repo history is a single squashed commit.

Smoke Test Results

Host-based run (sbx was not Docker-authenticated, so the documented host fallback was used): macOS 26.5.2, aarch64, Python 3.11.14, Node 24.13.1, shallow clone at 25 MB with 197 files. Repo stats API-verified 2026-09-14: 207 stars, 11 forks, created 2026-09-10, pushed 2026-09-12, 0 open issues, single commit, license NOASSERTION.

Run A. Fresh clone, no dependencies installed

$ git clone --depth 1 https://github.com/yjz211/vivid-figures-skill.git
✅ 25 MB, 197 files, single commit (author yjz211, 2026-09-13 00:37 +0800)
$ head -5 SKILL.md # frontmatter present?
✅ name: vivid-figures-skill; description 217 chars
$ resolve relative links in SKILL.md, README.md, docs/*.md, adapter, color guide
✅ 0 broken links across 6 files; 5/5 workflow+reference pairs exist
$ python3 verify recipe_registry.json content hashes
✅ 108/108 recipe sha256 values match; 0 duplicate IDs
$ grep network imports on the data-figure path; inventory .enc references
✅ zero network imports; 59 .enc files (1,436 KB) unreferenced by any executable

Pass rate: 5 of 5. Structure, integrity, and the security surface are clean with no dependencies installed.

Full structural log →

Run B. With deps preinstalled

$ python3.11 -m venv /tmp/vf-venv && pip install numpy pandas scipy matplotlib seaborn adjustText
✅ 17s, 314 MB (data-figure subset of the 21-package requirements.txt)
$ python original/resources/scripts/resolve_runtime.py
✅ exit 0; reports python/node/bash paths, optional tools as null until installed
$ python original/resources/scripts/bootstrap.py --workspace /tmp/vf-ws --profile modeling-competition --capability all
✅ .codex-plot-runtime.json written; 127 files copied into workspace _utils/
$ python _utils/get_recipe.py --id advanced.ridgeline
✅ exit 0, full recipe returned
$ python _utils/get_recipe.py --id basic.nonexistent
✅ non-zero exit with named error (unknown id rejected)
$ node --experimental-strip-types scripts/figure-plan-cli.mjs begin --workspace /tmp/vf-ws
✅ exit 0; .hajimi/figure-plan-policy.json written
$ node --experimental-strip-types scripts/figure-plan-cli.mjs validate --plan FIGURE_PLAN.json
✅ "valid": true on a contract-valid 9-figure plan (8 DATA + roadmap)
$ node ... validate --plan FIGURE_PLAN_BAD.json # only 2 figures
✅ rejected: "DATA requires at least 8 distinct figures"

Pass rate: 8 of 8. Every documented entry point works on first contact, and both negative cases fail loudly with named errors.

Full with-deps log →

Run C. Functional verification

$ python examples/palette-showcase/render.py --output /tmp/vf-showcase1
✅ 5 palette ridge PNGs (129-134 KB each, 1800x1170) + render-info.json audit
$ python render.py --output /tmp/vf-showcase2 && md5 both coral.png
✅ byte-identical across runs (md5 3ee8ac3b4ba0ab7715864a71269bcff8)
$ write CLAUDE.md palette markers, then setup_style() + plot_utils.heatmap/bar_compare
✅ PALETTE == marker colors 7/7 in order; heatmap PDF 19,445 B + PNG 126,015 B;
 bar_compare PDF 14,578 B; live QA warning fired on wasted margin
$ python bootstrap.py --workspace /tmp/does-not-exist-vf
✅ clean refusal: "Workspace does not exist", non-zero exit
$ HOME=/tmp/vf-home npx skills add yjz211/vivid-figures-skill --agent claude-code ... (and local-path variant with --agent hermes-agent)
✅ SKILL.md + all 197 files land; local install byte-identical to the clone

Functional pass rate: 6 of 6. The committed showcase audit reproduces exactly (colors, sample counts, medians); committed PNGs differ from my render only at the font-rasterization layer.

Full functional log →

What the runs tell you

The executable core (recipe retrieval, styling contract, rendering, plan validation, installation) works end to end with real assertions, and the failure paths are designed rather than accidental. What no host run can verify is the prompt-contract layer: whether a live agent actually follows the routing, asks about style and palette before drawing, and honors the three-round repair limit. That layer is the skill's main interface, so treat the functional score as verified plumbing, verified contract pending a live session.

Setup Walkthrough

1. Clone into your skills directory: git clone https://github.com/yjz211/vivid-figures-skill.git "$HOME/.claude/skills/vivid-figures-skill" (the universal route npx skills add yjz211/vivid-figures-skill --agent claude-code --skill vivid-figures-skill --copy --yes works too and landed all 197 files in my test).
2. Create the venv and install dependencies: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt. Budget for a large install; the six-package data subset alone was 314 MB, and the full list adds geopandas, PyMuPDF, CairoSVG, and more.
3. In a fresh Claude Code session over your data directory, tell the agent to use the skill and point it at the venv interpreter, per docs/INSTALL.md. This avoids the documented failure mode where the agent runs system Python without the deps.
4. Optional tools per figure class: draw.io Desktop for diagrams, XeLaTeX for TikZ, Chrome for HTML figures, Mermaid CLI for Mermaid; Node 22.6+ only if you use the full-atlas plan validator.

Post-install gotchas from my run: macOS renders logged STSong font-weight fallback warnings on every figure (benign, not in the troubleshooting table), and the workspace gains .codex-plot-runtime.json, .hajimi/, and _utils/ directories with legacy HaJiMi and Codex names.

Alternatives

1. anthropics/skills - the official Anthropic pack (GearScope 4/5) covers document and artifact creation with permissive licensing and English docs, but has nothing close to 108 plotting recipes or figure QA.
2. K-Dense-AI/scientific-agent-skills - scientific workflow skills in English (GearScope 3/5); broader research coverage, much shallower plotting guidance.
3. Plain matplotlib plus your own prompt - no license constraints and no install beyond what you already have; you give up recipe fidelity gates, palette management, and the automatic margin and overlap checks that make this skill's output consistent.