Feature: Support argument-hint field in Skills YAML frontmatter

Resolved 💬 3 comments Opened Apr 4, 2026 by mo-xiaoxi Closed Apr 7, 2026

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.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗