skip to content

In a Claude Code SKILL.md, what does a line like !`git status --short` do, and when does it abort the skill or get disabled?

level: seniorimportance: should knowfreq 10%

answer

  1. preprocessing, not a tool call
  2. output replaces the line
  3. one failure sinks the invocation
  4. rules checked, never prompted
  5. a setting swaps in a placeholder

basics

~20 s

Claude Code runs the command before the skill reaches Claude and inlines its output, so Claude sees data. A failing command, a deny rule, or outside auto mode any check short of allow aborts the invocation; disableSkillShellExecution swaps in a placeholder.

solid answer

~50 s

`` !`command` `` is **dynamic context injection**: when the skill is invoked, Claude Code runs the command through the Bash tool (or PowerShell) and inlines its output before sending the content, once, without re-scanning the output. It is recognised only at the start of a line or after whitespace, and a fenced block opened with ```` ```! ```` handles multi-line commands. Any non-zero exit aborts the entire invocation, except exit 1 from search and comparison commands such as `grep` or `git diff`. Injected commands never prompt: a deny rule aborts, and outside auto mode so does an ask rule, or a command no rule allows unless `allowed-tools` pre-approves it. `disableSkillShellExecution: true` replaces each command with `[shell command execution disabled by policy]`; in managed settings users cannot override it, and bundled and managed skills are exempt.

code

markdown · 17 lines
markdown
---
name: deploy
description: Deploy the current branch
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(git log *)
---

## Working tree
!`git status --short`

## Last commit
!`git log -1 --oneline`

## Lint report (exits 1 on findings, so keep it from aborting)
!`${CLAUDE_PROJECT_DIR}/scripts/lint-report.sh || true`

Deploy only if the working tree above is clean.

go deeper

for a junior

Recall that !command runs before Claude sees the skill and its output replaces the line.

for a middle

Explain the parsing rules, the fenced block form, and why one non-zero exit aborts the whole invocation.

for a senior

Show you can reason about permissions here: never a prompt, deny and non-allow results abort outside auto mode, and disableSkillShellExecution as the managed off switch.

for a principal

Weigh live context in skills against running shell on every invocation, and decide which skill sources an organisation should let execute at all.

## What injection is A skill's body can contain **dynamic context injection**: a line with `` !`<command>` ``, or a fenced block opened with ```` ```! ```` for multi-line commands. When the skill is invoked, Claude Code **runs the command first** and replaces the placeholder with its output. Claude receives the current `git status`, not the instruction to fetch it. This is preprocessing done by Claude Code, not a tool call Claude chooses to make. Three parsing rules matter: - Substitution runs **once** over the original file. Output is inserted as plain text and **not re-scanned**, so a command cannot emit a new placeholder for a later pass. - The inline form is recognised only when `!` is at the **start of a line or right after whitespace**. In `` KEY=!`cmd` `` the placeholder stays as literal text and nothing runs. - With the default `shell: bash`, stderr is merged into stdout, so error text lands in the injected output too. ## How the commands run Claude Code runs injected commands through the Bash tool, or the PowerShell tool when the skill sets `shell: powershell` and that tool is enabled. They share that tool's behaviour: the session shell's **current working directory** (which moves when Claude runs `cd`, so use `${CLAUDE_SKILL_DIR}` or `${CLAUDE_PROJECT_DIR}` in paths), the default **2-minute timeout**, and the inline output ceiling, past which output arrives as a file path plus a preview. Two details of that shared behaviour catch people out. When the Bash tool moves a timed-out command to the background, the skill **still renders**, and the injected text reports the move and names the background task and the file collecting its output. When the command is one the Bash tool never moves to the background, Claude Code **kills it at the timeout**, and that failure aborts the invocation. And because a command's output is part of the rendered skill, a re-invocation whose command produces new output appends the full skill content again rather than a short "already loaded" note. ## When an injected command fails A failed command **aborts the entire skill invocation**, not just its own line, and Claude never sees the skill content. The error reads `Shell command failed for pattern "..."` and includes the command's stderr. | Exit status (default bash shell) | Result | |---|---| | 0 | Output injected | | 1 from a search or comparison command, such as `grep`, `rg`, `diff` or `git diff` | Treated as a normal result; output injected | | 1 from any other command | Invocation aborts | | 2 or higher, for any command | Invocation aborts | A check script that exits 1 when it finds problems will therefore sink the skill. Append `|| true` to commands you expect to exit non-zero. ## Permission checks Injected commands **never show a permission prompt**. Instead Claude Code checks each against your permission rules before the skill renders: 1. A command a **deny rule** matches aborts the invocation with `Shell command permission check failed for pattern "..."`. 2. **Outside auto mode**, any result other than allow aborts the same way, including a rule that would normally ask you. 3. Listing the command in the skill's `allowed-tools` pre-approves it; deny and ask rules still win over that. 4. **In auto mode**, which is the starting permission mode for interactive terminal and VS Code sessions from **v2.1.283**, a command that would need approval does not abort. The skill loads with an instruction for Claude to run the command first, and Claude's own call then goes through auto mode's usual checks. A forked skill that sets `agent` still aborts. ## Why it is a risk, and how to turn it off Injection runs shell commands on your machine **whenever the skill is invoked**, and Claude can invoke a skill on its own when its description matches, unless it sets `disable-model-invocation: true`. A repository skill can therefore run commands as part of an ordinary request, so review a repository's `.claude/skills/` like its build scripts. - Setting `"disableSkillShellExecution": true` replaces each command in skills and custom commands from user, project, plugin or additional-directory sources with `[shell command execution disabled by policy]`. - A `true` in **managed settings** cannot be overridden by `false` elsewhere, which is where the setting is most useful. - **Bundled skills and skills deployed through managed settings are unaffected.** - Skills synced from a claude.ai account never run these commands on your machine, regardless of the setting (v2.1.228 or later).

  • A skill injects !`./scripts/lint-report.sh`, which exits 1 when it finds problems, and the skill never loads. Why, and what is the fix?
    Any non-zero exit aborts the whole invocation, and exit 1 is forgiven only for search and comparison commands such as `grep` or `git diff`. Append `|| true` so the script's findings are injected instead of sinking the skill.
  • How does an organisation stop repository and personal skills from running inline shell?
    Set `"disableSkillShellExecution": true` in managed settings, where users cannot override it with `false`. Commands in user, project, plugin and additional-directory skills become `[shell command execution disabled by policy]`; bundled and managed skills keep running theirs.
  • Could a command's output smuggle in a second !`...` placeholder that then runs?
    No. Substitution runs once over the original file, and output is inserted as plain text without being re-scanned, so a placeholder inside output stays text. Claude still reads that output, though, so untrusted content in it is a prompt-injection concern rather than a shell one.

Like a mail merge: the fields are filled in before the letter is sent, so the recipient reads your actual address, never the formula that fetched it — and if one field cannot be filled, the letter is not sent at all.

  • Claude always reads the !command itself and decides whether to run it.
  • A failing injected command just leaves its line empty.
  • Injected commands show a permission prompt like any other command.
  • A !`cmd` placed mid-word, like KEY=!`cmd`, still runs.
  • disableSkillShellExecution also stops bundled and managed skills' commands.

Assumes Claude Code 2.1.286; auto mode has been the starting permission mode for interactive terminal and VS Code sessions since v2.1.283, which changes what a would-prompt injected command does.