How to Use String Substitutions in Claude Skills: `$ARGUMENTS`, `$N`, and `${CLAUDESESSIONID}` Explained

Claude skills and commands support runtime string substitution using $ARGUMENTS for full argument lists, $N shorthands for positional arguments, and ${CLAUDESESSIONID} for session tracking, all expanded before execution begins.

The shanraisshan/claude-code-best-practice repository defines a lightweight templating system that enables dynamic behavior in Claude Code custom automations. Understanding Claude string substitutions allows developers to craft flexible skills and commands that respond to user input and session context without hardcoding values.

Substitution Syntax Fundamentals

According to best-practice/claude-skills.md and best-practice/claude-commands.md, the substitution engine recognizes specific placeholder patterns that are resolved at runtime.

Accessing Arguments with $ARGUMENTS and $N

The system provides three ways to reference incoming arguments:

• $ARGUMENTS – Expands to the full list of arguments joined by spaces.
• $ARGUMENTS[N] – Accesses the Nth argument using 0-based indexing (e.g., $ARGUMENTS[0] for the first argument).
• $N – Shorthand syntax for $ARGUMENTS[N] (e.g., $0, $1, $2).

When a user invokes /skillname arg1 arg2, the value $1 resolves to "arg2" while $ARGUMENTS resolves to "arg1 arg2".

Session Context with ${CLAUDESESSIONID}

As documented in .claude/hooks/HOOKS-README.md, the runtime automatically injects the unique session identifier using the ${CLAUDESESSIONID} placeholder. This variable is useful for logging, caching, or tying generated artifacts to a specific Claude session.

Practical Code Examples

Echo Skill with Positional Arguments

Define a skill in .claude/skills/echo/SKILL.md that demonstrates basic substitution:

--- 
name: Echo Skill
description: Demonstrates argument substitution
---
You passed the following arguments:
- First: $0
- Second: $1
- All together: $ARGUMENTS

Invoking /echo hello world produces:

You passed the following arguments:
- First: hello
- Second: world
- All together: hello world

Command Logging with Session ID

Create a command in .claude/commands/log-session/COMMAND.md that captures the current session:

--- 
name: Log Session
description: Saves the current session ID to a file
---
/bin/bash -c "echo Session ${CLAUDESESSIONID} > /tmp/claude_session.log"

After execution, /tmp/claude_session.log contains a value like Session c3f2a7b9-9d5e-4a6b-8f33-1e2d4f5a7b9c.

Dynamic API Requests

Use substitutions to parameterize external API calls in .claude/skills/fetch-weather/SKILL.md:

--- 
name: Weather Fetcher
description: Calls Open-Meteo with a city argument
---
{% raw %}
curl "https://api.open-meteo.com/v1/forecast?latitude=$0&longitude=$1&hourly=temperature_2m"
{% endraw %}

Running /fetch-weather 47.61 -122.33 substitutes the coordinates directly into the URL.

Passing Arguments to Sub-Agents

Reference arguments when defining agent prompts in .claude/agents/example-agent.md:

--- 
name: Example Agent
description: Shows argument passthrough to a sub-agent
---
Prompt: |
  The user wants to run: $ARGUMENTS
  Please summarise the intent.

When invoked as /example-agent generate diagram flow, the sub-agent receives the literal string "generate diagram flow" in its context.

Key Source Files and Implementation Details

The substitution behavior is formally defined in the following locations:

• best-practice/claude-skills.md – Documents the placeholder table for skill definitions, specifying $ARGUMENTS, $N, and indexing behavior.
• best-practice/claude-commands.md – Mirrors the skill syntax for command definitions, ensuring consistency across both extension types.
• .claude/hooks/HOOKS-README.md – Illustrates real-world usage of ${CLAUDESESSIONID} within hook implementations for session-aware workflows.

These files collectively specify that substitution occurs before execution, meaning downstream tools receive concrete values rather than placeholder syntax.

Summary

• $ARGUMENTS expands to all arguments joined by spaces, while $N provides shorthand access to the Nth positional argument.
• ${CLAUDESESSIONID} is injected by the Claude runtime and enables unique session tracking for logging and artifact management.
• Substitutions are processed pre-execution, ensuring bash scripts, API calls, and sub-agent prompts receive resolved string values.
• The syntax is identical across skills and commands as defined in claude-skills.md and claude-commands.md.

Frequently Asked Questions

What is the difference between $1 and $ARGUMENTS[1]?

There is no functional difference; $1 is simply a shorthand alias for $ARGUMENTS[1]. Both access the second argument (using 0-based indexing) passed to the skill or command at runtime.

How do I access the session ID in a Claude skill?

Reference ${CLAUDESESSIONID} anywhere in your skill or command body. The Claude runtime automatically injects the unique session identifier before executing the command, as documented in the hooks reference.

Can I use these substitutions in both skills and commands?

Yes. The placeholder syntax is identical for custom skills defined in .claude/skills/ and custom commands defined in .claude/commands/, ensuring a consistent templating experience across Claude Code extensions.

When exactly are these variables expanded?

Substitution occurs immediately before the skill or command body executes. This pre-processing step ensures that any downstream tools—whether bash scripts, API calls, or sub-agent prompts—receive literal string values rather than the placeholder syntax.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}