Substitution Variables

Complete reference for every substitution variable available in SKILL.md files. Variables are replaced with actual values at skill load time, before the agent sees the content.

$ARGUMENTS

Contains everything the user typed after the skill name, as a single string. This is the most common substitution variable and works well for free-form input.

---
description: Explain a concept in simple terms
---

The user wants you to explain the following topic:

$ARGUMENTS

Explain it as if teaching a junior developer.

Invocation: /explain dependency injection
Result: $ARGUMENTS becomes "dependency injection"

$1 through $9

Positional arguments are created by splitting the argument string on whitespace. Use these when your skill expects structured input with distinct parameters.

---
description: Rename a component across the codebase
---

Rename the React component from **$1** to **$2** across the entire codebase.

## Steps

1. Find all files that import or reference `$1`
2. Update the component name in its definition file
3. Update all import statements
4. Rename the file from `$1.tsx` to `$2.tsx`

${CLAUDE_SESSION_ID}

A unique identifier for the current agent session. Use this for creating temporary files or directories without naming collisions across sessions.

---
description: Run benchmarks and save results
allowed-tools:
  - Bash(*)
  - Write
---

Run the project benchmarks and save results to a unique file:

`benchmark-results-${CLAUDE_SESSION_ID}.json`

This ensures each session's results don't overwrite previous runs.

${SKILL_DIR}

The absolute filesystem path to the directory containing the current skill's SKILL.md. Always resolves to an absolute path regardless of where the agent was launched from.

---
description: Generate API documentation from OpenAPI spec
allowed-tools:
  - Read
  - Write
---

Read the documentation template from:
${SKILL_DIR}/templates/api-doc.md.hbs

Read the styling config from:
${SKILL_DIR}/config/doc-style.json

Use these to generate documentation for $ARGUMENTS.

!`command` — Dynamic Context

Runs a shell command at skill load time and replaces the expression with the command's stdout. This is a preprocessor step, not a tool invocation — it happens before the agent sees the skill content.

---
description: Review the current git changes
---

Current branch: !`git branch --show-current`

Staged changes:
!`git diff --cached`

Review these changes and suggest improvements.

Key Behaviors

• Executes at load time (Tier 2) — before the agent starts processing the skill.
• Runs once per invocation — invoking the same skill twice runs commands again.
• Sequential execution — commands run top to bottom. Slow commands delay loading.
• Combinable with variables — substitutions ($ARGUMENTS, $1, etc.) are applied first, then dynamic context commands execute.

---
description: Analyze the history of a specific file
---

Recent changes to $1:
!`git log --oneline -10 -- $1`

Last author: !`git log -1 --format='%an (%ar)' -- $1`

Analyze the change history and identify patterns.

Processing Order