${CLAUDE_SESSION_ID} Substitution is a runtime feature that replaces the placeholder ${CLAUDE_SESSION_ID} with the active session's UUID whenever a skill is loaded, enabling session-scoped state management and coordination.

How It Works

At skill load time, the Claude Code harness scans the skill's SKILL.md frontmatter and body text for the literal string ${CLAUDE_SESSION_ID} and substitutes each occurrence with the current session's UUID. The substitution is literal and happens before the skill instructions are presented to the agent; the session ID is then available as a concrete value throughout the skill's execution lifetime.

The Test

A skill was created with ${CLAUDE_SESSION_ID} embedded in its text. The skill was then invoked. The substitution occurred correctly: the placeholder was replaced with the observed session UUID 0ae83877-5583-4169-9adc-ea36d4a4392f. Four verified behaviors confirmed the feature's completeness: substitution worked, the ID remained consistent within the session, substitution succeeded in both frontmatter paths and body text, and no failures occurred under the test conditions.

Use Cases

The feature enables session-scoped state files (storing data in /tmp/state-${CLAUDE_SESSION_ID}.json), session-attributed logging, cross-skill coordination via session-specific file paths, and debugging attribution of artifacts back to their originating session. A single session ID can tag all output from a multi-skill workflow, making audit trails and state isolation straightforward.

Implementation Note

The substitution happens once, at load time, rather than dynamically on each reference. This makes the session ID a stable constant within the skill's execution, avoiding both evaluation complexity and the risk of ID instability mid-execution.