[DOCS] Skills and custom command docs omit unmatched positional placeholder behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

The “Available string substitutions” and “Pass arguments to skills” sections covering $ARGUMENTS[N] and the $N shorthand for positional arguments. The custom-command placeholder guidance in the Agent SDK slash-commands reference should be updated or cross-linked as well.

Current Documentation

The skills reference currently says:

$ARGUMENTS[N] | Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. $N | Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second.

It gives an example that uses three placeholders and only documents the fully supplied invocation:

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2]. Running /migrate-component SearchBar React Vue replaces $ARGUMENTS[0] with SearchBar, $ARGUMENTS[1] with React, and $ARGUMENTS[2] with Vue.

The Agent SDK reference likewise says custom commands support dynamic arguments and shows Fix issue #$0 with priority $1, but only demonstrates an invocation supplying both values:

Command will process with $0="123" and $1="high"

What's Wrong or Missing?

The documentation does not state what happens when a positional placeholder has no corresponding argument. Claude Code v2.1.210 fixed unmatched $1/$2 placeholders in skills and commands: instead of silently removing them, Claude Code now preserves them verbatim.

This is a user-visible contract for reusable skills and custom commands. For example, a skill containing Migrate the $0 component from $1 to $2 may be invoked with only two arguments. Without documented unmatched-placeholder behavior, authors cannot tell whether the remaining $2 will remain visible, become an empty string, or cause another rendering problem. Users can consequently receive incomplete instructions without understanding why, or mistake an intentionally preserved token for a successful substitution.

Suggested Improvement

Add a short rule to the positional-substitution documentation stating that, as of v2.1.210, an unmatched $N placeholder in a skill or custom command is preserved literally rather than stripped. Include a partial-argument example, such as:

Template: Migrate the $0 component from $1 to $2.
Invocation: /migrate-component SearchBar React
Rendered text: Migrate the SearchBar component from React to $2.

Clarify that this behavior is different from escaping a placeholder that should always be literal, for which the existing \$1 guidance applies. Add the same rule to, or link from, the Agent SDK custom-command “Arguments and Placeholders” section so skill and command authors see one consistent contract.

Impact

Medium - Makes feature difficult to understand

Additional Context

The behavior change was released in v2.1.210. The documentation currently explains successful positional substitution and escaping, but does not describe the no-match case.

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 270-285 | Positional substitution, quoting, and escaping rules |
| https://code.claude.com/docs/en/skills | 420-432 | Positional-placeholder example and fully supplied invocation |
| https://code.claude.com/docs/en/agent-sdk/slash-commands | 343-371 | Custom-command arguments and placeholder example |

Total scope: 2 documentation pages affected