Bundled Visualize skill documents the wrong relative path for scripts/render.py

Start with plugins/visualize/skills/visualize/SKILL.md and inspect the preview and export passages that reference scripts/render.py. Update both commands with skill-directory path resolution, then add the helper-path contract check to the package tests. Done means a newly materialized plugin has the clarified instructions, the existing skills/visualize/scripts/render.py helper, and passing preview validation.

Codex app version

26.721.31836 (macOS)

Plugin

visualize@openai-bundled, version 1.0.15, bundle variant live-disabled

Problem

The bundled Visualize skill documents this preview/export command:

python3 scripts/render.py <fragment> [<destination>.html] [--serve]

That path is ambiguous and fails from an ordinary project working directory. It also led an agent to resolve the helper from the plugin root:

<CODEX_HOME>/plugins/cache/openai-bundled/visualize/1.0.15/scripts/render.py

which does not exist.

The renderer is present one level tree deeper:

<CODEX_HOME>/plugins/cache/openai-bundled/visualize/1.0.15/skills/visualize/scripts/render.py

Reproduction

From an ordinary project directory, follow the skill's literal command:

python3 scripts/render.py /absolute/path/to/fragment.html /tmp/preview.html

Python looks for <project>/scripts/render.py and exits with code 2 because the file does not exist.

Resolving from the plugin root fails in the same way. Resolving from the directory containing the Visualize SKILL.md succeeds.

Root cause

SKILL.md uses scripts/render.py without saying that skill-relative helper paths resolve from the directory containing SKILL.md, rather than from the current working directory or plugin root.

Proposed minimal repair

Update plugins/visualize/skills/visualize/SKILL.md in both the preview and export passages:

- `python3 scripts/render.py <absolute-fragment-path> [<destination>.html] [--serve]`
+ Resolve `scripts/render.py` relative to the directory containing this
+ `SKILL.md`, not the plugin root or current working directory. Run:
+ `python3 <visualize-skill-directory>/scripts/render.py <absolute-fragment-path> [<destination>.html] [--serve]`

- `python3 scripts/render.py <absolute-fragment-path> <destination>.html`
+ `python3 <visualize-skill-directory>/scripts/render.py <absolute-fragment-path> <destination>.html`

No renderer or asset change is required.

Validation performed

I applied the documentation patch to an isolated copy of the packaged skill and ran a contract checker that:

1. verifies every documented local scripts/... or assets/... helper exists relative to the skill directory;
2. requires explicit path-resolution wording;
3. exports a fragment through render.py;
4. starts render.py --serve --port 0 and verifies the temporary URL returns the fragment as HTML.

Results after the proposed patch:

PASS: documented helper paths exist: scripts/render.py
PASS: standalone preview export works
PASS: temporary preview route returned HTML

The current packaged instructions fail the path-resolution contract as expected.

Suggested acceptance criteria

• Land the clarified skill-relative command in the canonical bundled-plugin source.
• Add the helper-path contract check to the package tests.
• Confirm a newly materialized plugin build contains the clarified instructions and the existing helper at skills/visualize/scripts/render.py.