Feature: Support argument-hint field in Skills YAML frontmatter
Problem
Currently, Commands support the argument-hint field in their YAML frontmatter, which displays parameter hints in the / slash menu (e.g., <feature-name> [--fast|--careful]). This helps users understand what arguments a command expects without reading its documentation.
However, Skills — which are the recommended successor to Commands per the Agent Skills Open Standard — do not support argument-hint or any equivalent field. When a Skill is user-invocable and appears in the / menu, there is no way to show parameter hints alongside the description.
Example
Command (current behavior — has argument hint):
---
description: "Spec-driven development workflow"
argument-hint: "<feature-name> [--fast|--careful|--normal]"
---
In the / menu, the user sees:
/dev-spec-dev <feature-name> [--fast|--careful|--normal]
Skill (current behavior — no argument hint):
---
name: dev-spec-dev
description: "Spec-driven development workflow..."
---
In the / menu, the user only sees:
/dev-spec-dev Spec-driven development workflow...
Proposed Solution
Add support for an argument-hint field (or equivalent like usage-hint) in the Skills YAML frontmatter:
---
name: dev-spec-dev
description: "Spec-driven development workflow"
argument-hint: "<feature-name> [--fast|--careful|--normal]"
---
This would allow Skills to display the same parameter hints that Commands currently support, making the migration from Commands to Skills seamless for plugin authors and their users.
Context
We maintain a large Claude Code plugin (DevAgent) with 60+ Commands that we are migrating to Skills. The lack of argument-hint in Skills is a friction point — users lose the parameter discoverability they had with Commands.
Alternatives Considered
- Embedding hints in
description: Works but clutters the description field, which has a different purpose (triggering semantic activation). - Keeping both Commands and Skills: Defeats the purpose of migrating to the newer standard.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗