[BUG] `argument-hint` not included in Skill tool metadata for agent-to-agent invocation

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The argument-hint frontmatter field in skills and slash commands is only shown in IDE/CLI autocomplete but is not included in the Skill tool description provided to agents.

Since skills and slash commands are now unified and both exposed to agents via the Skill tool, agents need visibility into argument-hint for both. When using context: fork, skills/commands receive arguments via the ARGUMENTS: line appended after content. However, calling agents have no visibility into the expected argument format because argument-hint is not included in the metadata.

The Skill tool lists both skills and slash commands as:

- skill-name: description text here
- command-name: description text here

Even when either defines argument-hint: [use-case-description], agents only see the name and description.

What Should Happen?

The argument-hint should be included in the Skill tool metadata so calling agents understand the expected invocation pattern. For example:

- skill-name: description text here. Arguments: [use-case-description]

Or in a structured format that agents can parse.

This is particularly important for:

1. Skills using context: fork which rely on ARGUMENTS for input
2. Agent-to-agent orchestration where the calling agent needs to know what input to provide
3. Alignment between human-facing hints and agent-facing metadata

Error Messages/Logs

No error — the field is silently omitted from agent-visible metadata.

Steps to Reproduce

1. Create a skill with argument-hint in frontmatter:

``yaml
# .claude/skills/test-skill/SKILL.md
---
name: test-skill
description: Test skill for argument hint
argument-hint: [your-input-here]
context: fork
---
# Test Skill
Process the provided input.
``

1. Create a slash command with argument-hint:

``yaml
# .claude/commands/test-command.md
---
description: Test command for argument hint
argument-hint: [action] [target]
---
# Test Command
Execute the requested action.
``

1. Start a new Claude Code session

1. Ask Claude to report the verbatim metadata available for those entries:

``
Look at your Skill tool. Report the verbatim details (name, description, argument-hint, etc.) shown for the test-skill and test-command entries.
``

1. Observe that only name and description are shown — argument-hint is missing for both

1. Compare with IDE autocomplete which DOES show the argument-hint when typing /test-skill or /test-command

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.9

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

Context: This was discovered while investigating skill architecture for agent orchestration. Skills and slash commands are now unified under the Skill tool, and the context: fork feature enables isolated execution where both receive input via ARGUMENTS:. Without argument-hint visibility, calling agents must rely solely on the description to understand expected input format.

Current workaround: Include the expected argument format in the description itself:

description: Get vault operation guidance. Invoke with your use case (e.g., "create entity for user profiles")

Documentation reference: The slash command docs show argument-hint as: "The arguments expected for the slash command. Example: argument-hint: add [tagId] | remove [tagId] | list"

This implies it's meant to communicate the invocation interface, which should be visible to both humans and agents for proper alignment.