What variant of Codex are you using?
CLI
What feature would you like to see?
Please support argument-hint in SKILL.md frontmatter as display metadata for explicit skill invocation.
Skills can already be invoked explicitly with $<skill-name>, but skills that behave like commands often have an expected argument shape. Today that hint has to live in prose inside the skill body, so the $ picker/composer can show the skill name and description but not the usage shape.
Claude Code supports this kind of argument-hint preview, and I find it very helpful in practice. I have occasions where I use Claude Code only because its terminal UI shows the skill argument-hint preview while composing.
For example:
---
name: yeet
description: Use for GitHub PR/issue/discussion workflows.
argument-hint: <create-pr|update-pr|create-issue|update-issue|comment-issue|create-discussion> [options]
---
Expected behavior:
argument-hint is parsed as an optional, first-class skill metadata field.- The
$ skill picker / autocomplete can display it alongside the name and description.
- When a skill is inserted into the composer, Codex can optionally surface the hint after the
$skill token, or otherwise make it visible while composing.
- Plugin and user skills get the same behavior.
This would make explicit skill invocation much more self-documenting, especially for command-like skills where the name alone is not enough.
Additional information
I couldn't find an existing feature request for this. The closest related item I found was #28628, which made the skills loader tolerate invalid YAML scalars in unknown frontmatter fields such as argument-hint. That fixes parsing tolerance, but it doesn't make argument-hint part of the skill metadata surface.
What variant of Codex are you using?
CLI
What feature would you like to see?
Please support
argument-hintinSKILL.mdfrontmatter as display metadata for explicit skill invocation.Skills can already be invoked explicitly with
$<skill-name>, but skills that behave like commands often have an expected argument shape. Today that hint has to live in prose inside the skill body, so the$picker/composer can show the skill name and description but not the usage shape.Claude Code supports this kind of argument-hint preview, and I find it very helpful in practice. I have occasions where I use Claude Code only because its terminal UI shows the skill
argument-hintpreview while composing.For example:
Expected behavior:
argument-hintis parsed as an optional, first-class skill metadata field.$skill picker / autocomplete can display it alongside the name and description.$skilltoken, or otherwise make it visible while composing.This would make explicit skill invocation much more self-documenting, especially for command-like skills where the name alone is not enough.
Additional information
I couldn't find an existing feature request for this. The closest related item I found was #28628, which made the skills loader tolerate invalid YAML scalars in unknown frontmatter fields such as
argument-hint. That fixes parsing tolerance, but it doesn't makeargument-hintpart of the skill metadata surface.