Claude Code Skill Arguments Changed $1? Escape Literal Dollars

Claude Code treats $0, $1, and other $N strings in SKILL.md as positional argument placeholders. That behavior is intentional when you want a Skill invocation to inject arguments. It is surprising when the same text is meant to be a shell variable, an awk field, a SQL placeholder, or a dollar amount.

The current documented fix is exact: prefix a literal dollar sign with one backslash. Write \$1 when the Skill must receive the literal characters $1. Do not use two backslashes before the dollar sign, because Claude Code still performs substitution in that form.

The Fast Fix

Review every $N occurrence in the Skill and classify it before changing anything:

Use positional placeholders only where argument injection is deliberate. Escape every literal dollar sign immediately followed by a digit.

Why This Happens

Claude Code Skills support three related argument forms:

• $ARGUMENTS inserts all arguments;

• $ARGUMENTS[N] inserts one zero-indexed argument;

• $N is shorthand for the same zero-indexed positional argument.

For example, invoking a Skill with two arguments can replace $0 with the first value and $1 with the second. The parser applies that substitution across the SKILL.md body, including prose and fenced code blocks. A code fence changes Markdown presentation, not argument parsing.

Anthropic's current Skills documentation also distinguishes indexed and named arguments. Indexed placeholders preserve shell-style grouping for quoted arguments. A missing indexed placeholder remains in the content, while a missing named argument becomes an empty string. Those details make it important to treat every placeholder as executable template syntax rather than decoration.

Step 1: Find Every Candidate

Start with a read-only inventory. On macOS or Linux, run this from the project root:

for root in "$HOME/.claude/skills" .claude/skills .agents/skills; do
  [ -d "$root" ] || continue
  rg -n --glob 'SKILL.md' '\$([0-9]|ARGUMENTS)' "$root"
done

On Windows PowerShell:

Get-ChildItem $HOME\.claude\skills, .claude\skills, .agents\skills `
  -Filter SKILL.md -Recurse -ErrorAction SilentlyContinue |
  Select-String '\$([0-9]|ARGUMENTS)'

Expected result: every line that can participate in argument substitution is listed with its file and line number. The commands do not modify any Skill.

Do not restrict the review to commands. Check examples, explanatory prose, SQL, regular expressions, prices, and reference snippets. A Skill can teach an agent the wrong command even when the substituted text is never executed directly.

Step 2: Classify Intent Before Editing

For each match, ask one question: should the value come from the Skill invocation?

Keep the placeholder when the answer is yes:

Review pull request $0 for repository $1

Escape it when the answer is no:

Print the first column with:

```sh
awk '{print \$1}' input.csv
```

The outer example above shows the source that belongs in SKILL.md. When Claude Code loads the Skill, the agent should see awk '{print $1}' input.csv.

Apply the same rule to embedded SQL:

Use a parameterized query such as `SELECT * FROM jobs WHERE id = \$

And to literal prices:

Reject estimates below \$0.10 per task

Avoid broad search-and-replace. A global replacement would break the intentional placeholders that make the Skill reusable.

Step 3: Use Exactly One Backslash

The escape rule is easy to overcorrect. These two source strings are not equivalent:

\$1    literal $1
\\$1   backslashes plus argument substitution

If a surrounding format also interprets backslashes, test the final SKILL.md bytes rather than reasoning from another template layer. The rule described here applies to the text Claude Code reads from SKILL.md.

Step 4: Verify on a Disposable Copy

Copy the Skill to a temporary test name or project before changing a widely installed version. Keep one intentional placeholder and one escaped literal in a small diagnostic section:

Intentional first argument: $0
Literal shell parameter: \$1

Invoke the test Skill with two distinctive arguments, such as ALPHA and BRAVO.

Expected result:

• the intentional $0 location becomes ALPHA;

• the escaped location remains the literal $1;

• no unrelated command, example, price, or SQL placeholder changes;

• quoted arguments remain grouped as the documentation describes.

Then run the inventory command again and manually confirm that each remaining unescaped placeholder is intentional. A clean audit does not mean zero matches. It means every match has a reason.

Common Failure Modes

Audit Third-Party Skills Before Installing Them

This bug class is one reason to inspect a Skill as executable supply-chain content, not as passive documentation. A Skill can combine argument templates, shell commands, helper scripts, and linked references. Review all of them before installation, as described in How to Audit an Agent Skill Before Installing It.

If you are deciding where the Skill belongs in a larger agent stack, use Agent Skills vs MCP vs CLI. Skills should hold reusable instructions and workflows; provider Actions and live external data should stay behind a typed integration boundary.

Recheck the Contract After Claude Code Updates

This guide reflects Anthropic's Skills documentation accessed on August 5, 2026, and the parser behavior reported in issue 84212. Recheck the current documentation after a Claude Code release that changes Skill arguments or escaping. If the product changes, update the Skill from the documented contract before removing any escape.

Monitor the Upstream Issue With Aident Loadout

After fixing your Skill, you can monitor the upstream GitHub issue without placing a GitHub token in the prompt. Install or update Aident Loadout with this exact instruction:

Follow https://aident.ai/SETUP.md

Then authenticate and discover a connected read-only GitHub Action:

aident account auth status
aident vault vault --action status
aident capabilities search \
  --queries '["find one connected read-only GitHub Action that searches issues"]' \
  --types '["action"]' \
  --targetEnv staging

Inspect the returned schema before execution. Success means the current issue state is retrieved through a reviewed Action, no provider secret appears in the chat, and no repository file changes.

Use Aident Loadout to verify the upstream issue after you repair the literal dollar signs.

Sources

• Extend Claude with Skills, Anthropic documentation, updated and accessed August 5, 2026

• Slash commands, Anthropic documentation, accessed August 5, 2026

• Agent Skills specification, accessed August 5, 2026

• Skill args are substituted into literal $0, $1, and $2 strings, Anthropic Claude Code issue, opened August 5, 2026

• Claude Code Skill Arguments: $ARGUMENTS, $1, $2, and $3, YouTube, published July 21, 2026