${CLAUDE_SESSION_ID} Substitution

1. Created skill with ${CLAUDE_SESSION_ID} in SKILL.md text

${CLAUDE_SESSION_ID} substitution is a runtime variable that replaces a placeholder token with the current session's UUID whenever a skill is loaded.

How It Works

The Claude Code runtime scans skill text (both SKILL.md frontmatter and body) for the literal string ${CLAUDE_SESSION_ID} and replaces it with a stable UUID at skill load time. The substitution is static per session: the same ID persists throughout all skill invocations within that session boundary.

Test Setup and Result

The 2.1.9 test created a skill containing ${CLAUDE_SESSION_ID} in its instructions, invoked it, and verified the placeholder was replaced with an actual UUID (0ae83877-5583-4169-9adc-ea36d4a4392f). The test passed. All verified behaviors held: substitution in frontmatter paths, consistency across invocations, and substitution in body text.

Key Use Cases

Session-scoped state files (/tmp/state-${CLAUDE_SESSION_ID}.json) allow ephemeral state to live outside a skill's lifetime without manual cleanup. Logging can tag artifacts with session attribution. Cross-skill coordination becomes possible by storing shared state in session-specific paths that multiple skills can discover and read. Debugging gains clarity: an artifact's provenance traces back to its generating session via the embedded ID.

Caveats

Substitution happens at skill load time only. The token must appear literally in source; computed or deferred interpolation does not work. Session boundaries are agent-runtime scoped: a session ID does not persist across separate Claude Code invocations or across EnterWorktree/ExitWorktree boundaries.

Evidence & receipt

file2.1.9/tests/01-session-id/TEST-RESULTS.md

◇ ed25519 receipt

idprimitive_055312bdaa8858a3b60e1190

alged25519

pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd

sig

531e57a1cc218ff602910d84edd4331ad0f8cf323b46343b4f15d7636c60669daaf3c0f6d19c027504844cf3c40c62d873c2e9cbb47bcd75585703ad4ea8f800

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected

instance-of Skill Runtime Class
introduces (in) 2.1.9 Test (2.1.9) Release
verifies (in) ${CLAUDE_SESSION_ID} Substitution — runtime test Test

${CLAUDE_SESSION_ID} Substitution

Primitive

Kind	Primitive
Introduced	Claude Code 2.1.9
Class	Skill Runtime
Epistemic	tested · runtime-test
Evidence	1 ref
Receipt	ed25519 · verifiable

Hands-on runtime test · Claude Code 2.1.9

Cite this page

Hunter, R. "${CLAUDE_SESSION_ID} Substitution." The Runtime Atlas. Content-addressed entity primitive_055312bdaa8858a3b60e1190, ed25519-signed (integrity, not third-party timestamp). https://ryanhunter.io/atlas/e/2-1-9-session-id

@misc{atlas-2-1-9-session-id,
  title  = {${CLAUDE_SESSION_ID} Substitution},
  author = {Hunter, Ryan},
  note   = {The Runtime Atlas; entity primitive_055312bdaa8858a3b60e1190; ed25519-signed for integrity},
  url    = {https://ryanhunter.io/atlas/e/2-1-9-session-id}
}