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 insert 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 disables 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. It inserts the output. It then sends the whole text to Claude.
String Substitutions
| Placeholder | Status | What it becomes | Notes |
|---|---|---|---|
$ARGUMENTS | Documented: An official docs page names this item. | All arguments as typed. | With no placeholder in the skill, Claude Code appends ARGUMENTS:. |
$ARGUMENTS[N], $N | Documented: An official docs page names this item. | One argument by index, counting from 0. | Shell-style quotes group words. A missing index stays as text. |
$name | Documented: An official docs page names this item. | A named argument from the arguments key. | A missing value gives an empty string. |
\$1 | Documented: An official docs page names this item. | The literal text $1. | One backslash before a token escapes it. \\$1 still expands. |
${CLAUDE_ | Documented: An official docs page names this item. | The session ID. | Claude Code does not replace it in synced skills. |
${CLAUDE_ | Documented: An official docs page names this item. | The current effort level. | low to max. |
${CLAUDE_ | Documented: An official docs page names this item. | The folder of the SKILL.. | Claude Code also replaces it in allowed- Bash rules. In a plugin it is the skill subfolder. |
${CLAUDE_ | Documented: An official docs page names this item. | The project root. | Claude Code replaces it in the body and in allowed-. |
${CLAUDE_, ${CLAUDE_ | Documented: An official docs page names this item. | Plugin paths. | Plugin skills only. |
${user_ | Documented: An official docs page names this item. | A saved plugin option. | Claude Code fills only non-sensitive values in skill and agent content. |
| Total size cap | Undocumented: Only the program shows this item. It can change without notice. | Stops huge fills. | The error says "This skill, command or hook and the arguments filled into it add up to more than N characters". The program marks argument values. A $ inside them is then not expanded. |
Shell Injection
| Syntax or setting | Status | What it does | Notes |
|---|---|---|---|
!`command` | Documented: An official docs page names this item. | Runs a command and inserts its output. | Only at the start of a line or after whitespace. Claude Code does not scan the output again. User, project, and plugin skills. |
A fenced block with ! after the opening backticks | Documented: An official docs page names this item. | A multi-line command. | The same rules. |
| A failing command | Documented: An official docs page names this item. | 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: An official docs page names this item. | Replaces each command with [shell command execution disabled by policy]. | The setting does not affect bundled and managed skills. |
| Synced skills | Documented: An official docs page names this item. | Never run ! commands. | Claude Code also does not expand @ files or two placeholders. |
Invocation Control
| Rule | Status | What it does | Notes |
|---|---|---|---|
| Default | Documented: An official docs page names this item. | You and Claude can both run the skill. | The description is always in context. |
disable- | Documented: An official docs page names this item. | Only you can run it. | The description is not in context. |
user- | Documented: An official docs page names this item. | Only Claude can run it. | Claude Code hides the skill from the / menu. |
| A name at the start of a message | Documented: An official docs page names this item. | 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: An official docs page names this item. | Permission rules for the Skill tool. | A deny on an alias blocks the bundled skill. Allow rules match the skill name only. |
| Lifecycle | Documented: An official docs page names this item. | 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: An official docs page names this item. | Runs the skill in a subagent. | Background by default. It waits in -, with CLAUDE_, and for scheduled tasks. |
| Commit-time skills | Undocumented: Only the program shows this item. It can change without notice. | 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).