Arguments and Substitution

The fixed-target problem

A skill that always does the same thing to the same target is limited. A code-review skill that only ever reviews the last commit is not as useful as one where you can type /review-pr 47 and have it pull up PR 47 specifically. Arguments turn a fixed procedure into a flexible command.

The $ARGUMENTS placeholder

The simplest way to pass data to a skill is $ARGUMENTS. Whatever you type after the skill name gets substituted for this placeholder before Claude sees the content:

---
name: fix-issue
description: Fix a GitHub issue by number
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue: !`gh issue view $ARGUMENTS`
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit that references the issue

Typing /fix-issue 123 substitutes 123 everywhere $ARGUMENTS appears. The gh issue view 123 command also runs via injection, pulling the actual issue content before Claude reads anything.

If your skill does not include $ARGUMENTS anywhere in its content, Claude Code appends ARGUMENTS: <your input> to the end of the skill so Claude still sees what you typed.

Positional arguments

When a skill takes more than one value, use indexed access. Arguments are 0-based and support two equivalent syntaxes:

---
name: migrate-component
description: Migrate a component between frameworks
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Or using the shorthand $N form:

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

Running /migrate-component SearchBar React Vue substitutes correctly. For arguments containing spaces, wrap in quotes: /migrate-component "Search Bar" React Vue makes $0 expand to Search Bar as a single value.

Named arguments via frontmatter

For skills with several parameters, named arguments improve readability. Declare the names in frontmatter; they map to positions in order:

---
name: generate-test
description: Generate tests for a function
arguments: [function, framework, coverage]
argument-hint: [function-name] [jest|vitest|pytest] [unit|integration]
---

Generate $coverage tests for the $function function using $framework.

Follow the project's existing test patterns and include edge cases.

Invoking /generate-test parseDate vitest unit makes $function = parseDate, $framework = vitest, $coverage = unit. The argument-hint field appears in the autocomplete dropdown so you can remember the expected order without opening the file.

To include a literal $ before a digit or recognized name in the skill body — for example, a price like $1.00 — escape it with a backslash: $1.00. A doubled backslash does not escape: \$1 leaves both backslashes and still expands $1 to the first argument.

Stacking skills

You can load multiple skills in a single message by typing them one after another at the start:

/code-review /fix-issue 123

Claude Code expands the first skill plus up to five more. The trailing text — 123 here — becomes $ARGUMENTS for every expanded skill. This is useful when you want a combined instruction set: review the code, and then fix the referenced issue.

Stacking stops at the first token that is not a user-invocable skill. A skill that runs as a forked subagent (covered in the next lesson) or a skill like /loop ends the stack expansion, and everything after it becomes the argument text.

The argument-hint field

The argument-hint value appears in the autocomplete dropdown when you type /skill-name in Claude Code. It does not affect how arguments are parsed — it is purely a reminder. Keep it short: something like [issue-number] or [filename] [format] is enough. The hint shows up before you press Enter, which is when you most need it.