When you run /fix-issue 123 high in Claude Code, how do $ARGUMENTS, $0, $1 and named arguments in the skill's SKILL.md get filled?
answer
- whole string versus positions
- zero-based, not shell-style $1
- quotes keep words together
- names map to positions in order
- unreceived input gets appended
basics
~20 s$ARGUMENTS becomes the whole string as typed, $0 and $1 take the first and second shell-quoted words, and names declared in the arguments frontmatter map to positions in order. Input no placeholder receives is appended as ARGUMENTS: <value>.
solid answer
~40 sEverything after `/fix-issue` is the argument string. `$ARGUMENTS` expands to all of it as typed, so `123 high`. Indexed forms are zero-based: `$ARGUMENTS[0]` or its shorthand `$0` is `123`, and `$1` is `high`; splitting uses shell-style quoting, so a quoted multi-word value stays one argument. With `arguments: [issue, priority]` in the frontmatter, `$issue` and `$priority` map to positions 0 and 1. An indexed placeholder with no matching argument stays as literal text, while a named one becomes an empty string. If no placeholder receives the input at all, Claude Code appends `ARGUMENTS: 123 high` to the content so Claude still sees it.
code
markdown · 13 lines---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
argument-hint: "[issue-number] [priority]"
arguments: [issue, priority]
---
Fix GitHub issue $issue (priority: $priority).
1. Read the issue description
2. Implement the fix and write tests
3. Create a commit that references issue $0go deeper
Recall that the text after /name becomes $ARGUMENTS, and that $0 is the first argument, not $1.
Explain zero-based indexing, shell-style quoting, the named arguments field, and what happens to missing or unreceived arguments.
Show you design skills that fail visibly: named arguments for optional values, quoting guidance in argument-hint, and no reliance on a placeholder that may stay literal.
Judge when a skill should take structured positional arguments at all versus free text Claude interprets, given how users actually type commands.
## Where arguments come from When you type a skill's name at the start of a message in Claude Code, everything after the name is the **argument string**. In `/fix-issue 123 high`, the string is `123 high`. Claude can pass arguments too when it invokes a skill through the `Skill` tool, and the same substitution rules apply. Claude Code expands the placeholders before the skill content reaches Claude, so Claude sees `Fix GitHub issue 123`, not a template. ## The placeholders | Placeholder | Expands to | For `/fix-issue 123 high` | |---|---|---| | `$ARGUMENTS` | The full argument string, as typed | `123 high` | | `$ARGUMENTS[N]` | The argument at 0-based position N | `$ARGUMENTS[0]` is `123` | | `$N` | Shorthand for `$ARGUMENTS[N]` | `$0` is `123`, `$1` is `high` | | `$name` | A name declared in the `arguments` frontmatter, by position | with `arguments: [issue, priority]`, `$priority` is `high` | The `arguments` field accepts a space-separated string or a YAML list, and names map to positions in order. A separate field, `argument-hint`, only changes what autocomplete shows, such as `[issue-number] [priority]`; it substitutes nothing. ## Splitting and quoting - Indexed and named arguments split on **shell-style quoting**. `/fix-issue "login page broken" high` makes `$0` the three words `login page broken` and `$1` the word `high`. - `$ARGUMENTS` is never re-split. It always expands to the full string as typed, quotes included. - Positions start at **zero**. Someone used to shell scripts expects `$1` to be the first argument; here it is the second. ## Missing and unreceived arguments These edge cases are where skills quietly misbehave: - An **indexed placeholder with no argument** at its position, such as `$2` when two arguments were passed, **stays in the content unchanged**, so Claude reads a literal `$2`. - A **named placeholder with no argument** expands to an **empty string**. - If you pass arguments and **no placeholder receives them**, Claude Code appends `ARGUMENTS: <your input>` to the end of the content, so the input is never silently dropped. A placeholder here means `$ARGUMENTS`, an indexed form, or a named argument. An indexed placeholder with nothing at its position does not count as receiving input, while a named placeholder does, because it expands to the empty string. ## Escaping and literal values 1. A value that itself contains placeholder text is inserted literally. With a body of `Summarize $0`, running `/summarize "$ARGUMENTS from yesterday"` gives Claude `Summarize $ARGUMENTS from yesterday`. 2. To write a literal dollar before a digit, `ARGUMENTS`, or a declared name, such as a price of `$1.00` in prose, escape it with one backslash: `\$1.00`. A doubled backslash does not escape, and the placeholder still expands. 3. The backslash escape covers only argument placeholders. `${CLAUDE_*}` variables such as `${CLAUDE_SKILL_DIR}` are still substituted after arguments are inserted. ## Arguments when a skill is invoked again Claude Code renders the skill, arguments included, each time it is invoked, and the rendered content enters the conversation as one message that stays there. When Claude re-invokes a skill and the rendered content is **identical** to the copy already in context, Claude Code adds only a short note that the skill is already loaded. When the content **differs**, for example because the arguments changed from `123` to `456`, the full content is appended again. Two runs of `/fix-issue` with different numbers therefore leave two rendered copies, each with its own values, rather than one template whose values were overwritten. ## Stacking several skills in one message You can put more than one skill at the start of a message. `/write-tests /fix-issue 123` loads both skills and passes the trailing text, `123`, as `$ARGUMENTS` to each. Claude Code expands the first skill plus up to five more after it, and stops at the first token that is not an inline, user-invocable skill: a skill that runs as a forked subagent ends the run there, and that token and everything after it become the argument text. ## Why this is asked A `/fix-issue` skill that writes `$1` for the issue number works in testing with two arguments and reads the wrong value in real use, or leaves a literal `$1` when only one argument is given. Knowing the zero-based positions, the literal-versus-empty rule, and the appended `ARGUMENTS:` line is the difference between a skill that degrades visibly and one that misleads Claude.
- The skill body contains no placeholder at all, and you type /fix-issue 123. What does Claude receive?The skill content with `ARGUMENTS: 123` appended at the end. Claude Code adds that line whenever you pass arguments and no placeholder receives them, so the input still reaches Claude instead of being dropped.
- How do you pass a bug title with spaces as a single argument?Quote it: `/fix-issue "login page broken" high`. Indexed and named arguments use shell-style quoting, so `$0` becomes the whole quoted title and `$1` becomes `high`. `$ARGUMENTS` still holds the full string as typed.
- What does Claude see in place of $2 when only two arguments were passed, and how does a named argument differ?A literal `$2`: an indexed placeholder with no argument at its position stays unchanged. A named placeholder from the `arguments` frontmatter with no matching argument expands to an empty string instead.
- $1 is the first argument, the same as in a shell script.
- Without a $ARGUMENTS placeholder, typed arguments are silently dropped.
- A missing $2 expands to an empty string.
- Every placeholder needs its names declared in the arguments frontmatter first.
- argument-hint defines the names that $name placeholders expand from.