An AI agent skill that turns any subject into a 3D film or app
Agent guide for this repository
This repository is the viz3d skill: a plugin that turns a subject into a 3D app or film. These rules are for a
coding agent that changes the repository. To use the skill, not to change it, read
plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md instead. People read CONTRIBUTING.md.
It has the same rules with more reasons.
Before you edit
- Read
plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.mdand only the reference files that your change touches. Do not load every file inreferences/. - Run
git status. Do not change or revert files that you did not touch. - Find where the thing lives:
| Change | Files |
|---|---|
| A look | references/looks.md (new section before ## Choosing, one row in ## Choosing), the looks table in README.md, the look words in skills/viz3d/SKILL.md, SKILL.md description |
| A mode | references/<mode>.md, shape table in SKILL.md, mode table in skills/viz3d/SKILL.md, README.md, both files in harness/ |
| A fault | the fault list in references/self-review.md or in the mode reference |
| An example | examples/<topic>.md, in the shape of examples/airport-ramp.md |
| A script | scripts/, and the reference that tells the agent when to run it |
| A harness | harness/<agent>/, plus the install and command tables in README.md |
Hard rules
skills/visualize-in-3d/SKILL.mdhas a maximum of 100 lines. Its frontmatter has onlyname,descriptionandlicense. Move detail into a reference file.skills/viz3d/SKILL.mdkeepsdisable-model-invocation: true, so the command runs only when a person types it.skills/viz3d/agents/openai.yamlkeepsallow_implicit_invocation: falsefor the same reason.- A mode word must match in all four places:
skills/viz3d/SKILL.md,harness/gemini/viz3d.toml,harness/opencode/viz3d.mdand theREADME.mdmode table. - No private data: no personal names, home folders, drive letters, internal tool names, project code names, API keys or tokens. A fault line carries no name or date of who reported it. Use
{{WORK_DIR}}and{{SKILL_DIR}}with forward slashes. - Assets and sounds need a reusable licence (CC0, CC BY) with the source named. Sound effects are real or made and mixed in layers.
- Scripts never read the wall clock or unseeded randomness. A frame depends only on its time.
- Do not add a dependency to a script without a reason in the pull request. The scripts run on Node 20 and ffmpeg.
- Prose follows plain technical English: short sentences, active voice, no em dashes, no semicolons in prose, no sales words.
Check before you finish
Run these from the repository root and fix every failure:
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
git diff | grep -niE "C:\\\\|/Users/|/home/|api[_-]?key|token" || echo "scrub clean"
If claude is not installed, say so in your report and still run the other checks.
Finish
- Raise
versioninplugins/<plugin>/.claude-plugin/plugin.jsonof each plugin you changed: patch for a fix or a fault, minor for a look, mode, script or harness. - Keep one topic in each commit. In the report, list the changed files and the checks with their result. Say what you could not check.
- Do not push, publish or open a pull request unless the person asked for it.