Official plugin skills can trigger description length validation errors

Open 💬 2 comments Opened Jun 3, 2026 by ElninoZhong
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What happened?

Codex repeatedly reports a length validation error while loading or validating skills. This is surprising because the skills involved appear to be official/plugin-provided skills, not only user-authored skills.

On my machine, the official Codex plugin cache contains many SKILL.md frontmatter descriptions that are substantially longer than a short description field. Examples from the local plugin cache:

918  .codex/plugins/cache/openai-curated/build-web-data-visualization/.../visualization-strategy-and-critique/SKILL.md
730  .codex/plugins/cache/openai-curated/build-web-data-visualization/.../uml-and-software-architecture-visualization/SKILL.md
722  .codex/plugins/cache/openai-curated/hyperframes/.../hyperframes/SKILL.md
550  .codex/plugins/cache/openai-curated/openai-developers/.../openai-platform-api-key/SKILL.md
501  .codex/plugins/cache/openai-curated-remote/data-analytics/.../index/SKILL.md
570  .codex/skills/.system/imagegen/SKILL.md

User-level skills were also checked separately: 73 skill directories / 73 SKILL.md files, frontmatter present, and no malformed frontmatter detected. This makes the error feel like the CLI is enforcing a schema/length constraint against official curated/bundled skill metadata that the official packages themselves do not satisfy.

Expected behavior

Official/bundled/curated skills should not produce user-facing length validation errors in normal Codex startup or skill loading.

If a length limit is intentional, Codex should either:

  • ensure all official skills satisfy that limit before shipping,
  • exempt trusted official plugin cache metadata from user-skill validation,
  • truncate or normalize official descriptions before feeding them into the schema-constrained path, or
  • show an actionable error that names the specific skill file and field that failed validation.

Actual behavior

Codex reports a generic/repeated length error, which is hard to act on. From the user perspective, this looks unreasonable because the affected skills appear to be official Codex plugin/runtime skills.

Environment

Codex Doctor v0.136.0
OS: macOS 26.5.1, arm64
Install method: npm
Package: @openai/codex
Runtime version: 0.136.0
Auth: ChatGPT auth configured
codex doctor: 16 ok, 1 warn, 0 fail degraded

codex doctor itself did not fail on skills, so this may be specific to the runtime path that loads/exposes skills/plugins rather than the base doctor checks.

Additional context

This came up after updating Codex to 0.136.0 and refreshing a shared local skill library. The local user-skill library validates cleanly, while the official plugin cache contains many long official descriptions. The key request is to make the validator and official skill metadata consistent, and to make any remaining error identify the exact skill and field instead of only saying the length is wrong.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #25996

Powered by Codex Action

Toshi3886 · 2 months ago

I can confirm the same class of issue with heygen@openai-curated on Codex CLI 0.137.0 / Windows / PowerShell.

The plugin is installed and enabled, but Codex skips two skills because their SKILL.md frontmatter description fields exceed 1024 characters:

  • heygen-avatar: 1388 characters
  • heygen-video: 1543 characters

Startup warning:

⚠ Skipped loading 2 skill(s) due to invalid SKILL.md files.

⚠ %USERPROFILE%\.codex\plugins\cache\openai-curated\heygen\cd0fccd4\skills\heygen-avatar\SKILL.md: invalid
  description: exceeds maximum length of 1024 characters

⚠ %USERPROFILE%\.codex\plugins\cache\openai-curated\heygen\cd0fccd4\skills\heygen-video\SKILL.md: invalid description:
  exceeds maximum length of 1024 characters

I opened a narrower duplicate with the HeyGen-specific details at #27074, but this issue appears to be the better canonical OpenAI/Codex-side tracking issue. I also opened an upstream HeyGen issue for shortening the SKILL.md descriptions: https://github.com/heygen-com/skills/issues/90