viettranx/3dviz-pro-max

Turn an idea into a 3D scene worth exploring.

_{Visual inspiration, not a benchmark. An author-supplied project recorded before this skill existed; its UI contains Vietnamese. Historical footage, not an English demo or a runtime test of the skill — see media provenance.}

Landing page · Install · Examples · Skill · Prompts · Compatibility

A standalone agent skill for creative 3D visualization: shape the world, model its rules, make it interactive, and check what actually appears on screen. It ships a ten-step workflow, a searchable catalog of recipes and reusable knowledge, runnable Three.js templates and kits, and a capture helper so the agent inspects the frames it rendered instead of describing them. Factual explanations need sources; animated decoration does not become a simulation just by moving.

Start with one sentence:

Use 3dviz-pro-max to build a small fantasy village I can explore. Choose a distinctive art direction, add a few moving creatures, and inspect the result.

You do not need to choose a renderer or fill out a specification first. The agent should use the existing project stack, choose an appropriate representation, and refine the scene from observed results.

Runtime captures on a real GPU from the skill's own kits, rigs and recipes — all twenty-one frames, with host, tiers and hashes, are in the showcase gallery.

The whole island at dusk from the home camera.	Night: lantern practicals are the only key light.	Same island as a tabletop model, 22° lens.
Timber cottage at T3, the Blender-baked hero.	Stone bridge over the running water surface.	A 24/16-tooth spur pair, module 10 mm, ratio 3:2.

Village frames come from the retired pilot revision at mixed tiers; kit frames use the blueprint proof harness at the tier named. Nothing is cropped or retouched, and no frame claims a tier its record calls missing.

As of 2026-09-10, from catalog-summary.json and the docs below:

The landing page recomputes every one of these from skills/, docs/, evals/ and evidence/ at build time, so a number cannot drift from the data behind it.

graph LR
  A[Intent and<br/>visual direction] --> B[Reason about<br/>the objects]
  B --> C[Route: reuse kit /<br/>adapt / author / source]
  C --> D[Build a<br/>first view]
  D --> E[Run and capture<br/>real frames]
  E --> F[Refine by subject<br/>and evidence]
  F --> G[Report what was<br/>built vs observed]
  F -.-> C

• A workflow, not a lecture. Ten steps in SKILL.md: intent, object reasoning, grounding the representation, construction routing, quality targets and tool discovery, first view, meaningful behavior, run-and-inspect, refinement, honest reporting. Small edits use only the relevant steps.
• Creative direction before templates. Silhouette, proportions, parts, connections and behavior are decided first; kits speed suitable work and their T0–T4 pipeline labels do not cap artistic quality or factual fidelity.
• Concrete starting values. 69 knowledge records carry authored defaults — style profiles, mood lighting rigs, kit blueprints, a hero detail ladder, camera and time-of-day records — each stating palette, sky, fog, light rig, tone mapping and exposure, camera, materials, motion and post. 21 recipes carry numeric defaults with a worked expected value. Candidates to adapt, not mandatory settings.
• Runnable starting points. templates/ ships a Vite + Three.js scaffold with colour management, tone mapping and a viewer contract, five rigs (orbit camera, sun, night lantern, studio, post stack), three artifact document templates, two inspection checklists, and the kit library of 22 proved blueprints.
• Frames, not assurances. scripts/capture.py drives a built scene through its named views and clicks, then writes PNGs and the console log. Behavior stays tied to authoritative state; factual claims are researched before modeling and cross-checked against the rendered scene.

The skill supplies guidance, curated data and starting files. Your agent supplies the tools that create, run and inspect the artifact. The Python helpers search the catalog and drive an already-built scene in a browser; they do not render or judge a scene themselves, and capture needs an optional Playwright install.

The canonical skill is the whole skills/3dviz-pro-max/ folder — copy it together, never SKILL.md alone.

Claude Code reads it two ways; pick one, or the agent may load the older copy.

# Skill folder (personal or project), symlink a checkout you are editing
ln -s "$(pwd)/skills/3dviz-pro-max" ~/.claude/skills/3dviz-pro-max

# Or load the repository root as a plugin, from a checkout or the packaged ZIP
claude --plugin-dir /path/to/3dviz-pro-max
claude --plugin-dir 3dviz-pro-max-0.1.0-plugin.zip

Plugin skills are namespaced, so the menu entry reads /3dviz-pro-max:3dviz-pro-max; the folder route is invoked as /3dviz-pro-max. The marketplace manifest lists the repository itself:

/plugin marketplace add viettranx/3dviz-pro-max
/plugin install 3dviz-pro-max@3dviz-pro-max

That route needs the repository published first, and it clones the whole repository, evidence and showcase media included; it is untested (see below).

Codex is the first evaluation target: install the same folder in a skill location recognized by your installed Codex version, check that it appears in the session's available skills, and name it explicitly in your first prompt.

<your-agent-skill-directory>/
└── 3dviz-pro-max/
    ├── SKILL.md
    └── ... accompanying data and references

Observed, honestly: on 2026-09-09 with Claude Code 2.1.265 on macOS, claude plugin validate --strict passed for both manifests and a headless session loaded the skill from --plugin-dir on the checkout and on the packaged ZIP. Marketplace install/update/removal, the personal-folder route, Codex app installs and the Claude app upload path are untested, and no public marketplace listing is claimed. None of it proves rendering — run a scene prompt and inspect the frames. Full status: compatibility.

examples/ holds 37 directly addressable English studies in five chapters — anatomy and physiology, mathematics, physics and mechanisms, crafted worlds and props, lighting studies. Each folder carries its generation prompt, the skill rules actually reflected in the artifact, sources, controls and limits.

cd examples
pnpm install
pnpm dev        # open /<id>/, e.g. http://localhost:4180/heart/

site/ builds the project's one-page site: the 37 studies as demo cards with a hover clip and a modal that opens the runnable study, the counters above read from this repository at build time, the "how one sentence becomes a scene" loop, and the installation text read from docs/installation.md. It serves the built studies at /examples/<id>/.

pnpm --dir examples install --frozen-lockfile
bash site/scripts/bundle-examples.sh   # builds examples/ into site/public/examples/
pnpm --dir site install --frozen-lockfile
pnpm --dir site build                  # build-data → tsc --noEmit → vite build

The page is live at 3dviz.dev (Cloudflare Pages; anatomy geometry served from R2). Build steps, byte budgets, measured sizes and caveats: docs/site.md.

skills/3dviz-pro-max/   canonical skill: SKILL.md, data, references, templates, kits, scripts
examples/               37 runnable Three.js studies + shared runtime
site/                   React + Vite landing page (reads the repository at build time)
docs/                   installation, compatibility, coverage, roadmap, demos and showcase
evals/                  controlled skill-behavior evaluations and scorecards
evidence/               public evidence policy, dataset change logs, retired pilot artifacts
schemas/                record and manifest JSON schemas
scripts/                validation, index build, docs/retrieval checks, packaging
tests/                  Python unit tests

• Recipes describe how to model and verify a subject; they do not imply that every recipe has been rendered. Anatomy still needs verified geometry, and ideal kinematics is distinct from contact dynamics.
• Knowledge records are source-checked, editorially reviewed authoring guidance — not runtime observations. No Blender export, decoder, solver, browser or renderer was run for the Blender/Three.js knowledge batches.
• Of the 22 kit blueprints, T2 (procedural textures and vertex-baked occlusion) is proved on 18 and the four exceptions say why; T3 is the two Blender bakes (timber-cottage-t3.glb, watermill-t3.glb); T4 ships nowhere. hero-tier.py reports Blender's absence instead of faking a tier.
• The controlled before/after run scored four with-skill rounds at 19 → 23 → 23 → 25 out of 30 against a baseline of 21. A real direction of travel and a thin margin; at n=1 per condition it is not a demonstration that the skill makes better scenes.
• Prompt-gallery suggestions are not certified outputs. A failed or skipped check is useful information and must remain visible.

Contributions should add useful knowledge, clear sources and reproducible observations. Creative choices need rationale; factual claims need evidence. Read CONTRIBUTING.md and data contribution guidance, then run the gates from the repository root:

python3 scripts/validate.py
python3 scripts/build-index.py --check
python3 scripts/check-docs.py
python3 scripts/check-retrieval.py
python3 -m unittest discover -s tests
python3 scripts/package.py

Security-sensitive reports follow SECURITY.md. See also the changelog, the public evidence policy and the roadmap.

The repository's own code, data and authored media are released under the MIT license — copyright (c) 2026 Viettranx. Third-party material keeps its own terms and is not covered by that grant:

• BodyParts3D anatomy meshes (the STL geometry behind the anatomy studies) are from BodyParts3D, credited under CC BY-SA 2.1 Japan. Source registration and attribution must be preserved.
• Bundled fonts (Outfit, JetBrains Mono) are under the SIL Open Font License 1.1; see site/public/fonts/OFL.txt.
• The Harness Village recording (docs/demos/harness-village.gif and the transcoded copies under site/public/media/origin/) was supplied by the author from a project made before this skill existed. Its redistribution rights are still to be confirmed; its presence is not a blanket license for the depicted assets. See media provenance.