[DOCS] `skills` docs do not explain `\$` escaping for a literal `$` before digits in command bodies

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Available string substitutions and Pass arguments to skills, especially the positional $0/$1 placeholder rules for skill and custom-command bodies

Current Documentation

The skills docs currently say:

| $ARGUMENTS | All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. | | $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. |

Later on the same page, the positional example says:

Migrate the $0 component from $1 to $2.

The Claude directory guide also reinforces the same placeholder syntax:

Skills accept arguments: /deploy staging passes "staging" as $ARGUMENTS. Use $0, $1, and so on for positional access

and:

$ARGUMENTS substitutes whatever you typed after the command name. For positional access, use $0 $1 and so on.

What's Wrong or Missing?

The live docs explain how $ARGUMENTS, $ARGUMENTS[N], and $N placeholders expand, but they do not document the new escape rule for writing a literal dollar sign immediately before a digit in a skill or custom-command body.

The v2.1.163 release entry under review says:

Skills: added \$ escape syntax to include a literal $ before a digit in command bodies

That leaves one important authoring gap:

A. There is no documented way to write a literal dollar-plus-digit sequence

When a skill or command body needs text such as $10, $1/day, or another literal $ followed by a digit, the current docs do not explain how to prevent Claude Code from interpreting that sequence as a positional placeholder.

B. The current placeholder examples make collisions likely but undocumented

Because the docs actively teach $0, $1, and $2 for positional access, users writing pricing text, shell snippets, or prose inside SKILL.md and .claude/commands/*.md have no documented guidance for when a literal $ before a digit should be escaped as \$.

Suggested Improvement

Add a short note directly below the string-substitutions table in https://code.claude.com/docs/en/skills explaining the literal-dollar escape rule.

Suggested wording:

To include a literal $ immediately before a digit in a skill or custom-command body, escape the dollar sign as \$. For example, \$10 renders as literal $10, while $0 still expands to the first positional argument.

Then add one matching example in the argument-substitution section or the Claude directory guide so readers can see both forms side by side:

Budget: \$10 per run keeps the literal dollar amount. Fix issue $0 still uses positional substitution.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 249-263, 392-412 | Documents $ARGUMENTS, $ARGUMENTS[N], and $N plus positional examples, but not how to escape a literal $ before a digit |
| https://code.claude.com/docs/en/claude-directory | 222, 293-304 | Repeats the $0/$1 positional-access guidance for skills and commands, but does not mention the new \$ escape syntax |

Total scope: 2 pages affected

Version context: The missing behavior corresponds to the v2.1.163 release entry under review:

Skills: added \$ escape syntax to include a literal $ before a digit in command bodies