Show arguments without assuming input validation

Learning objective

Use argument-hint to show expected invocation parameters in autocomplete; distinguish a hint from runtime argument validation.

Core idea

argument-hint improves the moment when a developer selects a skill. It displays the expected arguments in autocomplete, such as [subsystem] or [filename] [format]. It does not define a required-parameter schema, reject missing values, or prove that the supplied value identifies a valid target.

Treat the invocation as three separate concerns: show the input convention, substitute the supplied text into the skill’s instructions, and decide whether that text is sufficient for the task. The frontmatter hint handles the first concern. $ARGUMENTS and positional placeholders handle the second. The task’s instructions or an executing validator must handle the third; the hint does not supply it.

This matters when a familiar-looking invocation initiates work on a repository. A visible hint reduces omissions, but the skill still needs an explicit response to missing or ambiguous scope instead of silently analyzing whatever Claude chooses.

How it works

Describe the expected input in autocomplete

Put the hint in the skill’s YAML frontmatter. For a saved subsystem review, use a concrete description of what the caller should provide:

---
name: subsystem-review
argument-hint: "[subsystem] [review-focus]"
disable-model-invocation: true
---

Review subsystem $0 with focus $1.
If either input is missing or ambiguous, ask for clarification
before inspecting the subsystem. Return findings with file evidence.

The hint labels the inputs; the body says how they affect the task. The square brackets are display text for the input convention, not a declaration that Claude Code checks two required values. An author could write a different label without changing runtime validation because no such validation is attached to this field.

The body instruction to ask for clarification is guidance to Claude. It is useful, but it is not a deterministic gate enforced by argument-hint. If execution must reject invalid input regardless of model behavior, the program that performs the operation needs its own input checks. Do not represent the hint or the clarifying instruction as that programmatic check.

Substitute the arguments that were actually supplied

Claude Code supports $ARGUMENTS for the complete argument string. For /subsystem-review auth security, a body that says Review $ARGUMENTS receives the full text auth security.

For individual positions, use $ARGUMENTS[N] or $N, with zero-based indexing. $0 is the first argument, and $1 is the second. These placeholders are substitution interfaces, not input validators. In the example, they place auth and security into separate parts of the task.

Indexed arguments use shell-style quoting. /subsystem-review "payment gateway" reliability passes payment gateway as the first argument and reliability as the second. Without quotation marks, the words become separate positions. The full $ARGUMENTS string preserves the argument text as typed, so it serves a different purpose from an indexed field.

Claude Code also documents named positional arguments through the arguments frontmatter field. Names map to positions in order, and $name inserts the matching argument. Recognize this as another substitution mechanism, not a way to turn an autocomplete hint into a typed input contract.

Understand missing-input behavior

If an indexed placeholder has no argument at its position, Claude Code leaves that placeholder as literal text. A missing $1 does not automatically stop the workflow or open a required-field dialog. A named placeholder whose position has no argument expands to an empty string instead. The two forms have different missing-value behavior, and neither establishes semantic validity.

If the user supplies arguments and no placeholder receives one, Claude Code appends them to the skill content as ARGUMENTS: <your input>. That keeps the supplied text visible to Claude even when the author omitted an argument placeholder. It does not mean the workflow consumes the text in the intended way.

Consequently, review both the displayed hint and the rendered task. A skill that advertises two parameters but uses only the first can still produce output. The fact that it ran tells you neither that the second value was checked nor that the developer’s requested focus influenced the result.

Match the response to the input defect

For an omitted subsystem, write an explicit instruction to request the subsystem before inspection. For an ambiguous name, ask for a repository path or other discriminating scope. For a supplied path, require the review to report which files it actually inspected. These are task instructions that make the result assessable; they do not add hidden behavior to the hint.

Keep the correction close to the invocation contract. Replacing argument-hint with a paragraph in a separate README loses the autocomplete cue. Adding the hint without any missing-input instruction leaves the execution ambiguity. The two improvements address different stages of the same interaction.

Key distinctions and trade-offs

Autocomplete hint versus argument substitution: The hint shows what to type. Placeholders insert what was typed. Changing the hint alone does not change which values the body uses.

Substitution versus validation: An argument can be present and still identify the wrong subsystem. Copying its text into the prompt establishes presence in context, not existence, authorization, or correctness.

Model clarification versus enforced rejection: A skill can instruct Claude to ask rather than guess. A hard input gate belongs to the code that executes the operation. Keep that distinction explicit when selecting controls for consequential actions.

Positional input is compact for predictable invocations. It becomes easier to misuse when values contain spaces or developers forget their order. A clear hint, documented quoting, and a body that states each value’s role reduce confusion without pretending the skill has a formal parameter schema.

Architecture / decision scenario

A developer productivity team uses /subsystem-review to investigate one service area. Engineers often invoke it without a target, and the resulting reports cover whichever files Claude happens to choose. The team adds argument-hint: "[subsystem] [review-focus]" so autocomplete exposes the expected input before invocation.

It also changes the body to use $0 for the subsystem and $1 for the focus, and instructs Claude to ask when either is missing or ambiguous. /subsystem-review auth security now expresses both dimensions of the intended review. /subsystem-review "payment gateway" reliability preserves a multi-word subsystem as one position.

A bare invocation still has no runtime rejection supplied by the hint. The team therefore assesses whether Claude requests clarification and whether the report names the inspected scope. If a separate operation requires guaranteed rejection of invalid input, the executing validator owns that guarantee. Selecting argument-hint answers the autocomplete problem, not every problem in the workflow.

Common exam traps

• Reading [subsystem] as an enforced required parameter.
• Assuming argument-hint substitutes values into the task body.
• Using $1 for the first positional argument instead of $0.
• Treating a present string as proof of a valid repository target.
• Assuming a missing indexed argument automatically aborts the invocation.

Where the exam guide differs

What to remember

Use argument-hint to show the expected invocation shape. Use $ARGUMENTS, $ARGUMENTS[N], or $N to consume supplied arguments. Keep missing-input guidance and any deterministic validation separate from those display and substitution mechanisms.

Knowledge check

References

• Anthropic, Extend Claude with skills
• Anthropic, Claude Certified Architect – Foundations Exam Guide