Shorten SKILL.md descriptions to fit the 1024 character Agent Skills limit

[Toshi3886]

Summary

The HeyGen SKILL.md frontmatter description fields appear to exceed the public Agent Skills / Codex loader limit of 1024 characters. As a result, Codex CLI skips loading the HeyGen skills when the plugin is installed through heygen@openai-curated.

Why this matters

Codex and other Agent Skills hosts load only each skill's name and description up front, then load the full SKILL.md body after a skill is selected. The frontmatter description is capped at 1024 characters. Longer usage guidance should live in the markdown body or references rather than the YAML description field.

Observed in Codex CLI

Environment where this was observed:

• Codex CLI: 0.137.0
• Platform: Windows / PowerShell
• Plugin: heygen@openai-curated
• OpenAI-curated cache version: cd0fccd4
• Local skill frontmatter version: 3.1.0 # x-release-please-version

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

Measured from the OpenAI-curated cached plugin:

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

Current repository check

The current main branch in this repository also appears to have descriptions longer than 1024 characters:

• heygen-avatar/SKILL.md: about 1429 characters
• heygen-video/SKILL.md: about 1525 characters
• heygen-translate/SKILL.md: about 1622 characters

Suggested fix

Please shorten each YAML frontmatter description to <= 1024 characters, ideally much shorter, and move the detailed routing rules / chain signals / exclusions into the markdown body.

For example, the description can focus on the concise trigger:

description: Create or manage persistent HeyGen avatar identities for presenter videos. Use before heygen-video when the user needs a new avatar, digital twin, presenter identity, or avatar/voice pair.

Then keep the longer chain-signal and NOT-for guidance below the frontmatter in the body.

I also opened a corresponding OpenAI Codex issue because the failing plugin is distributed as heygen@openai-curated: openai/codex#27074