Substitutions and Invocation
A skill body can hold placeholders that Claude Code fills in when the skill runs.
It can also run shell commands and paste in their output.
This page lists the placeholders, the shell syntax, and the rules for who can start a skill.
For example, $ARGUMENTS in a SKILL.md file becomes the text that you type after the command.
disableSkillShellExecution turns off shell injection. disable-model-invocation and user-invocable control who can run a skill.
Example
.claude/skills/fix-issue/SKILL.md
---
description: Fix a GitHub issue by number.
arguments: issue
allowed-tools: Bash(gh issue view *)
---
Issue details:
!`gh issue view $issue --json title,body`
Fix issue $issue. Session: ${CLAUDE_SESSION_ID}.
Type /fix-issue 42. Claude Code runs gh issue view 42, pastes the output, and sends the whole text to Claude.
String Substitutions
| Placeholder | Status | What it becomes | Notes |
|---|---|---|---|
$ARGUMENTS | Documented | All arguments as typed. | With no placeholder in the skill, Claude Code appends ARGUMENTS:. |
$ARGUMENTS[N], $N | Documented | One argument by index, counting from 0. | Shell-style quotes group words. A missing index stays as text. |
$name | Documented | A named argument from the arguments key. | A missing value gives an empty string. |
\$1 | Documented | The literal text $1. | One backslash before a token escapes it. \\$1 still expands. |
${CLAUDE_ | Documented | The session ID. | Not replaced in synced skills. |
${CLAUDE_ | Documented | The current effort level. | low to max. |
${CLAUDE_ | Documented | The folder of the SKILL.. | Also replaced in allowed- Bash rules. In a plugin it is the skill subfolder. |
${CLAUDE_ | Documented | The project root. | Replaced in the body and in allowed-. |
${CLAUDE_, ${CLAUDE_ | Documented | Plugin paths. | Plugin skills only. |
${user_ | Documented | A saved plugin option. | In skill and agent content only non-sensitive values are filled. |
| Total size cap | Undocumented | Stops huge fills. | The error says "This skill, command or hook and the arguments filled into it add up to more than N characters". Argument values are marked so a $ inside them is not expanded. |
Shell Injection
| Syntax or setting | Status | What it does | Notes |
|---|---|---|---|
!`command` | Documented | Runs a command and inserts its output. | Only at the start of a line or after whitespace. The output is not scanned again. User, project, and plugin skills. |
A fenced block with ! after the opening backticks | Documented | A multi-line command. | The same rules. |
| A failing command | Documented | Aborts the whole invocation. | The error is Shell command failed for pattern ".... Exit code 1 from search commands is a normal result. A permission failure says Shell command permission check failed. |
disable | Documented | Replaces each command with [shell command execution disabled by policy]. | Bundled and managed skills are not affected. |
| Synced skills | Documented | Never run ! commands. | @ files and two placeholders are not expanded either. |
Invocation Control
| Rule | Status | What it does | Notes |
|---|---|---|---|
| Default | Documented | You and Claude can both run the skill. | The description is always in context. |
disable- | Documented | Only you can run it. | The description is not in context. |
user- | Documented | Only Claude can run it. | The skill is hidden from the / menu. |
| A name at the start of a message | Documented | Runs the skill. | After plain text it only grants permission. You can stack up to five more skills in a terminal prompt. |
Skill(name) and Skill(name *) rules | Documented | Permission rules for the Skill tool. | A deny on an alias blocks the bundled skill. Allow rules match the skill name only. |
| Lifecycle | Documented | The skill text stays in the conversation. | An identical second run adds a short note. Compaction keeps 5,000 tokens for each skill and 25,000 in total. See Context and Compaction. |
context: | Documented | Runs the skill in a subagent. | Background by default. It waits in -, with CLAUDE_, and for scheduled tasks. |
| Commit-time skills | Undocumented | The names verify, pr, commit, code-, simplify, and go. | The program uses this set when it builds commit text. The docs name verify and simplify (2.1.286). |
Related Pages
- Skills and Commands: where skills live.
- Skill Frontmatter:
arguments,allowed-tools,context. - Subagent Runtime: what a forked skill runs in.
Source: Extend Claude with Skills, Settings Reference, and the program (the strings quoted in the tables).