Claude Commands

Claude Code Commands

Custom slash commands for Claude Code: prompt files invoked with /name, with argument substitution and dynamic shell context.

Custom commands have merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing .claude/commands/ files keep working and support the same frontmatter. Skills add a directory for supporting files, invocation control, and automatic loading when relevant — so create new commands as skills, and use .claude/commands/ only for single-file prompts you already maintain there. The full skill-authoring guide is the claude-skills skill; this skill covers the command surface: naming, frontmatter, arguments, and dynamic context.

File Locations and Command Names

• Use kebab-case directory and file names; the name on disk is the name typed.
• When a skill and a command file share a name, the skill takes precedence. Across levels, personal overrides project; enterprise managed settings take precedence over both. Plugin skills are namespaced, so they cannot conflict with other levels.
• In a plugin skill, the frontmatter name field replaces the last segment of the command (my-plugin/skills/review/SKILL.md with name: fancy → /my-plugin:fancy). In personal and project skills, name is only a display label — the command still comes from the directory name.

Frontmatter Reference

YAML between --- markers at the top of the file. All fields are optional; description is recommended so Claude knows when to load the command automatically. Malformed YAML loads the body with empty metadata: /name still works, but Claude has no description to match against.

Do not put allowed-tools on skills in THIS marketplace — test/validate-plugin.nu rejects it as a hard failure; tool allowlists belong on agents here. The field itself is valid upstream Claude Code frontmatter, which is why the table documents it.

Argument Substitution

Placeholders in the body are replaced before Claude sees the content. This means a doc that shows the literal token gets it substituted too when the doc itself loads as a skill. Two different markers keep this page intact, because one escape does not cover both forms:

• \$ARGUMENTS forms carry a leading backslash — the documented escape for a literal $ (see "Substitution rules" below). Drop the backslash to get the real placeholder.
• The CLAUDE_* names are written bare, because that same backslash does not escape the braced form. See the note under the table.
• Digit-indexed forms ($0, $1, $2, ...) and an undeclared $name need no marker: with no arguments passed at load time they render unchanged, which is why they appear undecorated throughout this page.

The four CLAUDE_* rows are written bare on purpose. In a real command you use them as brace expansions — a dollar sign, an opening brace, the name, a closing brace. They cannot be shown in that form here: the leading-backslash escape does NOT work on the braced form. Verified by loading this file as a skill — \ before a braced token leaves the backslash in place AND still expands the token, so writing them out would print this session's real ID and paths into the documentation. The backslash escape works only on the bare \$NAME form, which is why the $ARGUMENTS rows above can use it.

Indexing is 0-based: $0 is the FIRST argument and $1 is the SECOND. This runs against shell convention (where $1 is the first parameter) and is the easiest mistake to make when writing commands.

Substitution rules:

• Quoting is shell-style. /my-skill "hello world" second gives $0 = hello world, $1 = second. \$ARGUMENTS always gets the full string as typed.
• Missing arguments differ by kind. An indexed placeholder with no corresponding argument ($2 when only one argument was passed) stays in the content unchanged — this is exactly why the digit-indexed examples on this page ($0, $1, $2) are safe to show undecorated: this skill declares no arguments: and loads with none, so every indexed placeholder above has "no corresponding argument" and renders literally. A named placeholder with no matching argument expands to an empty string.
• Named arguments map by position. With arguments: [issue, branch], $issue expands to the first argument and $branch to the second.
• Escaping a literal $: a single backslash directly before the token, e.g. \$1.00. A doubled backslash (\\$1) does NOT escape — both backslashes stay and $1 still expands. A backslash before any other $ is left unchanged. This same backslash is the marker used throughout this page's \$ARGUMENTS placeholders so they stay literal while this doc itself loads. The CLAUDE_* names in the table above are shown bare instead, because the backslash does not escape the braced form.
• No \$ARGUMENTS in the body? When a command is invoked with arguments but contains no \$ARGUMENTS, Claude Code appends ARGUMENTS: <input> to the end of the content so Claude still sees what was typed.
• Stacked invocations: typing /write-tests /fix-issue 123 at the start of one message loads both commands and passes the trailing text 123 as \$ARGUMENTS to each.
• CLAUDE_SKILL_DIR and CLAUDE_PROJECT_DIR also substitute inside Bash rules in allowed-tools, so a command can pre-approve exactly the bundled script its body tells Claude to run.

Dynamic Context Injection

Shell output can be inlined into the command content before Claude reads it. The examples below carry a KEY= prefix immediately before every ! trigger, for the same reason the previous section escapes $ placeholders with a backslash: showing the live syntax unguarded would run it, or corrupt it into a live diff, while this very page loads. Drop KEY= to get the real syntax.

• Inline: KEY=!`git diff HEAD` on a line — the command runs and its stdout replaces the placeholder.
• Fenced (multi-line): a code fence opened with an info string of exactly ! (shown here as ```KEY=! to keep this line inert) runs the commands and inlines the output.

This is preprocessing, not Claude executing a tool: every command runs before Claude sees anything, and Claude receives only the rendered result. Substitution runs once over the original file — command output is not re-scanned for further placeholders.

The inline ! is recognized only at the start of a line or immediately after whitespace — in the text Claude Code actually scans, which is the text after markdown code-span delimiters are stripped, not the markdown source as written. Wrapping a bang in backticks does not by itself supply that preceding whitespace: only a real, visible character immediately before the bang in the rendered text does, which is why KEY=!`cmd` stays literal (the KEY= is real text, not a delimiter) while merely removing the space that might otherwise sit between an opening double-backtick and the bang does not — the delimiters were never counted as separating characters to begin with.

There is no file-inclusion placeholder. To inject a file's content, use KEY=!`cat path/to/file` (drop KEY=).

To block injection for user, project, plugin, and additional-directory sources, set "disableSkillShellExecution": true in settings; each command is replaced with [shell command execution disabled by policy]. Bundled and managed skills are not affected.

Plugin Wiring

Plugin commands ship two ways:

• Plugin skills (preferred): directories under <plugin>/skills/, listed in the plugin.json skills array. Invoked as /<plugin>:<name>.
• Command files: the plugin.json commands field — a single path string or an array of .md file and directory paths; a directory entry loads every .md file in it.

See the claude-plugins skill for the full plugin.json schema and validation scripts.

Security

• Never hardcode secrets — API keys, passwords, tokens, private URLs — in command files. Command bodies are prompts checked into repos and plugins.
• Treat KEY=!`command` (drop KEY=) lines as executable code in review: they run on invocation, before anyone reads the output. Audit third-party skills and plugins for injection lines and allowed-tools grants before installing; project-level allowed-tools takes effect only after the workspace trust dialog is accepted.
• Use disable-model-invocation: true for commands with side effects (deploy, commit, send-message) so Claude cannot trigger them on its own.
• In managed environments, enforce disableSkillShellExecution through managed settings, where users cannot override it.

Examples

Complete worked commands — \$ARGUMENTS, $N, named arguments, and dynamic injection — are in references/examples.md.

References

• Claude Code docs, "Extend Claude with skills" (covers custom commands): https://code.claude.com/docs/en/slash-commands
• claude-skills skill — full skill-authoring guide (structure, supporting files, evaluation)
• claude-plugins skill — plugin.json schema for shipping commands in plugins
• core:anti-fabrication skill — command bodies are prompts; verify every claim they make about tools, files, and behavior before shipping them