CONCEPT Substitutions turn a static file into a live prompt
A command body is a template. Before it reaches the model, Claude Code performs substitution: it fills in the arguments you typed, runs any bash you injected, and can include file contents. The result is a fully-rendered prompt — the model never sees the raw placeholders.
| Placeholder | Expands to |
|---|---|
$ARGUMENTS | All arguments passed after the command name, as one string. |
$ARGUMENTS[N] | A single argument by 0-based index — $ARGUMENTS[0] is the first. |
$N | Shorthand for $ARGUMENTS[N]. So $0 = first arg, $1 = second, $2 = third. |
$name | A named argument declared in the arguments: frontmatter list (maps to positions in order). |
$0 (or $ARGUMENTS[0]) is the
first argument, so $1 is the second. Values are shell-quoted — wrap multi-word
values in quotes to keep them as one argument. $ARGUMENTS always holds the full string as typed.$ARGUMENTS placeholder, Claude Code appends ARGUMENTS: <your input> to the end
so the model still sees what you typed.CONCEPT ! runs bash, @ pulls in a file
Two injection forms enrich a command with real, current data:
- Bash injection
!`command`— Claude Code runs the command first and replaces the placeholder with its output, so the prompt arrives with live data (a diff, a status, versions) already inlined. This is preprocessing, not something the model executes. The inline form is only recognized when!is at the start of a line or after whitespace. For multi-line commands, use a fenced```!block. - File reference
@path/to/file— includes that file's contents so the model can read it directly in the prompt.
allowed-tools, e.g. allowed-tools: Bash(git diff:*) or Bash(gh *).
Managed settings can shut it off entirely with "disableSkillShellExecution": true, which replaces
each command with [shell command execution disabled by policy].DIAGRAM The render pipeline
$ARGUMENTS, $0, $1…"] B --> C["Run !bash injections
output replaces placeholder"] C --> D["Inline @file contents"] D --> E["🟢 Fully-rendered prompt → model"] C -.->|"tool not in allowed-tools"| X["🔴 blocked / needs approval"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class E ok; class X bad;
CODE A command using all three
Positional args, live bash output, and a file reference in one template:
--- description: Summarize a pull request argument-hint: [pr-number] allowed-tools: Bash(gh *) --- # Live data — !`...` runs BEFORE the model sees anything - PR diff: !`gh pr diff $ARGUMENTS` - Changed files: !`gh pr diff --name-only $ARGUMENTS` # Pull a file's contents straight into the prompt - Contribution rules: @CONTRIBUTING.md # Positional args are 0-based: $0 is the FIRST argument Focus the summary on the "$0" area if one was given. ## Task Summarize PR #$ARGUMENTS for a reviewer.
Running /pr-summary 42 auth makes $ARGUMENTS = 42 auth,
$0 = 42, and $1 = auth.
TRADE-OFFS !`bash` injection vs. letting Claude run the tool
✅ Inject with !`…`
- Data is in the prompt before the model reasons
- Deterministic — always fetched, no "did it decide to?"
- Grounds the response in the real working tree
⚠️ Let Claude call the tool itself
- Flexible — Claude picks what/when to run
- May skip a step or run a different command
- Costs an extra turn; less reproducible
EXAM TRAPS
$1 is the first argument." → Indexed args are 0-based:
$0 / $ARGUMENTS[0] is first, so $1 is the second. Use
$ARGUMENTS for everything at once.!`cmd` means Claude will run the command." → It is
preprocessing — Claude Code runs it and inlines the output before the model sees the prompt.
The model only reads the result.allowed-tools, and managed policy can disable it entirely with
disableSkillShellExecution.! in the file triggers a command." → Only when ! is at
the start of a line or after whitespace. KEY=!`cmd` stays literal text.PRACTICE
Q1 · A command has body "Migrate $0 from $1 to $2." What does /migrate SearchBar React Vue produce?
"Migrate SearchBar from React to Vue." Because indexing is 0-based:
$0=SearchBar, $1=React, $2=Vue.
Q2 · How do you put the current git status output into a command's prompt automatically?
Use bash injection: !`git status --short` on its own line, and permit it with
allowed-tools: Bash(git status:*). Claude Code runs it and inlines the output before the model
sees the prompt.
Q3 · You pass arguments but the body has no $ARGUMENTS. Are they lost?
No. Claude Code appends ARGUMENTS: <your input> to the end of the rendered
content so the model still sees what you typed.