An AI agent skill that turns any subject into a 3D film or app
Contributing to viz3d
Thanks for helping. This guide is for people. If you work through a coding agent, point it at AGENTS.md. That file has the same rules in the order an agent needs them.
What helps most
- A fault you saw. Maybe a film had a hidden hit, or a caption went by too fast. Open an issue with the prompt you used, the agent and model, and one frame that shows the fault. We add it
to a fault list in
references/self-review.mdorreferences/action.md, so every later run checks for it. - A new look. You need a style that the current looks do not cover. Add a section to
references/looks.md(see below). - An example topic. You built a place or a system that went well. Add it to
examples/as a topic file. - A harness adapter. Your agent needs its own command file to run
/viz3d. - Fixes to the scripts in
scripts/.
For a large change, such as a new mode or a new script, open an issue first. That way we can agree on the shape before you spend time on it.
Layout
.claude-plugin/marketplace.json marketplace entry for Claude Code
plugins/visualize-in-3d/
.claude-plugin/plugin.json plugin name and version
skills/visualize-in-3d/ the skill
SKILL.md entrypoint, read first by every agent
references/ one file per mode or topic, read on demand
examples/ topic files for real places and systems
scripts/ recording, checks and the mock feed
agents/openai.yaml Codex display name and invocation policy
skills/viz3d/ the /viz3d command
harness/gemini/viz3d.toml /viz3d for Gemini CLI
harness/opencode/viz3d.md /viz3d for OpenCode
How to add things
A look
- Add a
## <Look name>section toreferences/looks.md, before## Choosing. - Describe the look in the same order as the other sections: palette, light, materials, camera, effects, and what breaks it.
- Add one row for the look under
## Choosing. - Add the look to the looks table in
README.md, the look words inskills/viz3d/SKILL.mdand thedescriptionofSKILL.md.
A mode
- Add
references/<mode>.mdwith the steps for the mode and its own fault list. - Add one row to the shape table in
SKILL.mdand a mode word to the table inskills/viz3d/SKILL.md. - Update the mode list in
README.mdand inharness/gemini/viz3d.tomlandharness/opencode/viz3d.md.
An example topic
Copy the shape of examples/airport-ramp.md: the real parts and their sizes, what moves, the beats, the look and
the camera. Use made-up company and people names. Cite the sources for real sizes and procedures.
A fault
Add one line to the matching list in references/self-review.md (generic faults) or in the mode's reference. Write
what the fault looks like in a frame and how to measure it, not only its name.
Rules for every change
SKILL.mdstays under 100 lines. Move detail into a reference file and link to it.- Frontmatter of
skills/visualize-in-3d/SKILL.mdhas onlyname,descriptionandlicense. Other keys make the upload to claude.ai fail. Theviz3dcommand can also useargument-hintanddisable-model-invocation. - No private details. No user names, home folders, drive letters, company names or internal tools. A fault line says what went wrong and how to measure it, with no name or date of who saw it. Write paths
as
{{WORK_DIR}}and{{SKILL_DIR}}, with forward slashes. - Assets and sounds must have a licence that lets anyone reuse them, such as CC0 or CC BY. Name the source and the licence. Sound effects are real recordings or sounds you made and mixed in layers, not one beep per hit.
- Write plainly. Use short sentences, active voice and one name for one thing. Do not use em dashes or sales words.
- Every frame is a function of time. Scripts and briefs never read the wall clock or
Math.randomwithout a seed.
Check your change
Run these from the repository root before you open a pull request:
claude plugin validate .
claude plugin validate plugins/visualize-in-3d
for f in plugins/visualize-in-3d/skills/visualize-in-3d/scripts/*.js plugins/visualize-in-3d/skills/visualize-in-3d/scripts/*.mjs; do node --check "$f"; done
bash -n plugins/visualize-in-3d/skills/visualize-in-3d/scripts/contact-sheet.sh
wc -l plugins/visualize-in-3d/skills/*/SKILL.md
If you changed what the agent does, run the skill once on a small subject. Attach a contact sheet or a short clip to the pull request.
Versions
Raise version in the .claude-plugin/plugin.json of the plugin you changed (plugins/<plugin>/) in the same pull request:
- patch (0.3.0 to 0.3.1) for a fix or a new fault,
- minor (0.3.0 to 0.4.0) for a new look, mode, script or harness.
Pull requests
Keep one topic in each pull request. Say what changed, why, and how you checked it. By contributing, you agree that your work is released under the MIT licence of this repository.