Codex plugin skill quality findings: path-root clarity, file hygiene, and progressive disclosure

Summary

An audit of live Codex plugin-provided SKILL.md files on Windows found several skill-quality issues that are not destructive, but can mislead Codex agents or create false validation failures. These mostly involve plugin-root path wording, overly broad mandatory reads, and host file-hygiene conflicts.

Environment

• Host: Codex on Windows PowerShell
• Scope audited locally:
  • OpenAI bundled Browser / Chrome / Computer Use plugin skills
  • OpenAI primary-runtime Presentations skill
  • OpenAI-curated Google Drive plugin google-docs
  • Figma remote plugin skills
• Local plugin cache roots included:
  • C:\Users\Charl\.codex\plugins\cache\openai-bundled
  • C:\Users\Charl\.codex\plugins\cache\openai-primary-runtime
  • C:\Users\Charl\.codex\plugins\cache\openai-curated-remote

Findings

1. Browser and Chrome plugin skills should define plugin-root path resolution

Affected skills:

• openai-bundled/browser/.../skills/control-in-app-browser/SKILL.md
• openai-bundled/chrome/.../skills/control-chrome/SKILL.md

Observed issue:

The skills reference scripts/browser-client.mjs in the plugin root and show imports from <plugin root>/scripts/browser-client.mjs. General Codex skill rules often resolve relative links from the directory containing SKILL.md first, so validators or agents can incorrectly search under the skill directory.

Suggested fix:

Add a short path map near the first support-file reference:

• skill_dir = directory containing this SKILL.md
• plugin_root = plugin version root containing scripts/browser-client.mjs
• scripts/browser-client.mjs resolves from plugin_root, not skill_dir

2. Computer Use skill has the same plugin-root ambiguity and a large body

Affected skill:

• openai-bundled/computer-use/.../skills/computer-use/SKILL.md

Observed issue:

The skill references scripts/computer-use-client.mjs in the plugin root. The skill body is also large, with API reference material inline.

Suggested fix:

Define skill_dir and plugin_root explicitly. Consider moving nonessential API reference material into linked references while preserving safety-critical rules in SKILL.md.

3. Presentations skill should define nested support and asset roots

Affected skill:

• openai-primary-runtime/presentations/.../skills/presentations/SKILL.md

Observed issue:

The skill mixes container_tools/, references/, builtin_templates_support/, and assets/builtin_templates/... paths. Without a root map, support-file validators can misclassify valid paths as missing.

Suggested fix:

Add a concise path-root map for:

• skill directory;
• support script root;
• built-in template support root;
• built-in template asset root.

4. Google Docs DOCX staging guidance should be narrowly scoped

Affected skill:

• openai-curated-remote/google-drive/.../skills/google-docs/SKILL.md

Observed issue:

The DOCX-first staging guidance can be read as overriding Codex's host-level file-edit and deletion discipline. It discouraged tracked file-edit tools such as apply_patch for helper scripts and directed cleanup of local staging artifacts after import.

Why it matters:

Persistent helper-file edits in Codex should follow host-native file-edit rules. User-provided files, reusable helper files, or workspace-visible artifacts should not be deleted without explicit confirmation.

Suggested fix:

Limit no-helper-script and cleanup guidance to ephemeral task-owned scratch artifacts. Preserve host-native file-edit rules for persistent helper files. Require explicit confirmation before deleting user-provided, reusable, or workspace-visible artifacts.

Local mitigation:

This one was patched locally because the skill is active and prompt-visible in the audited session.

5. Figma plugin skills could improve progressive disclosure

Affected skills:

• openai-curated-remote/figma/.../skills/figma-use/SKILL.md
• openai-curated-remote/figma/.../skills/figma-generate-design/SKILL.md

Observed issue:

Both skills are large and contain forceful prerequisite language. Much of the content is operationally important, but it increases prompt load and makes routine Figma tasks expensive.

Suggested fix:

Keep hard safety constraints and actual tool-call prerequisites in SKILL.md; move uncommon API details and task-variant guidance into references.

Validation Notes

The audit did not find direct destructive command examples in these plugin skills. The issue is compatibility, clarity, and progressive-disclosure quality rather than immediate destructive behavior.