skip to content

Invocation & Arguments

How a skill runs: typed as /name with $ARGUMENTS, or loaded by Claude when its description matches, with frontmatter deciding who may invoke it. Asked because custom slash commands are now skills.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

In Claude Code, what happens to existing .claude/commands/*.md files now that custom commands are merged into skills?

level: juniorimportance: must knowfreq 24%

answer

  1. one system, two file layouts
  2. both create the same /name
  3. name clash: which layout wins
  4. fields a command file lacks
  5. subfolders become colon names

basics

~10 s

They keep working. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way; the skill wins a name clash, and new work should use the skill folder.

solid answer

~30 s

Custom commands were folded into skills, not removed. A Markdown file in `.claude/commands/` is the older layout of the same thing: `.claude/commands/deploy.md` and `.claude/skills/deploy/SKILL.md` both give you `/deploy`, take `$ARGUMENTS`, and accept the same frontmatter except `name` and `paths`. The command name comes from the file name, and a subfolder becomes a colon prefix, so `.claude/commands/frontend/component.md` is `/frontend:component`. If both layouts define the same name, the skill runs. The docs recommend the skill folder for new work because it can hold supporting files beside `SKILL.md`, and it supports `name` and `paths`. Nothing forces a migration.

code

bash · 9 lines
bash
# Before: the older layout, still valid
#   .claude/commands/deploy.md          -> /deploy
#   .claude/commands/frontend/component.md -> /frontend:component

# After: the skill layout, same /deploy command
mkdir -p .claude/skills/deploy
git mv .claude/commands/deploy.md .claude/skills/deploy/SKILL.md
# supporting files can now live beside SKILL.md
cp docs/deploy-runbook.md .claude/skills/deploy/runbook.md

go deeper

for a junior

Recall that the two layouts are one system now: both give you /name, and the old command files still work. Know that the skill folder wins when names collide.

for a middle

Explain how each layout derives its command name, including the colon prefix for subfolders, and which two frontmatter fields a command file lacks.

for a senior

Show you can migrate a team's commands without breaking anything: shadowing during the move, deleting the old file, and adding supporting files only where they earn their place.

for a principal

Weigh whether migrating a large command library is worth the churn at all, given that nothing forces it, against the benefit of supporting files and consistent review.

## One system, two file layouts Claude Code once had two separate ideas: **custom slash commands**, Markdown files in `.claude/commands/`, and **skills**, folders holding a `SKILL.md`. They have been **merged**. Today both are skills, and both produce a command you type as `/name` at the start of a message. The docs state it directly: a file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way, and existing `.claude/commands/` files keep working. So the honest answer to "do I have to migrate?" is **no**. A team that has a folder full of command files loses nothing. What changed is the vocabulary and the recommendation for new work. ## How each layout gets its command name The name you type comes from where the file lives: | Layout | Name source | Example | |---|---|---| | `.claude/commands/<file>.md` | File name without extension | `.claude/commands/deploy.md` gives `/deploy` | | `.claude/commands/<dir>/<file>.md` | Subfolder path with `/` replaced by `:`, then the file name | `.claude/commands/frontend/component.md` gives `/frontend:component` | | `.claude/skills/<dir>/SKILL.md` | Frontmatter `name`, or the folder name | `.claude/skills/fix-issue/SKILL.md` gives `/fix-issue` | The same pattern holds in your home directory: `~/.claude/commands/` and `~/.claude/skills/` are the personal equivalents. ## What a command file can and cannot do A command file is a full participant in the skill system, with a few gaps: - It accepts the **same frontmatter** as `SKILL.md`, including `description`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable` and `allowed-tools`. - It does **not** accept `name` (the file name is the command name) or `paths` (so it cannot be limited to files matching a glob). - It takes **arguments** the same way: `$ARGUMENTS`, `$0`, `$1` and named arguments all expand. - It can use **dynamic context injection** with `` !`command` `` lines, and the `disableSkillShellExecution` setting covers it as well. - It is **a single file**, so it has nowhere to keep supporting files such as a reference document or a helper script. That is the main reason the docs say to prefer a skill for new work. ## When both layouts define the same name If a project has both `.claude/commands/deploy.md` and `.claude/skills/deploy/SKILL.md`, **the skill runs** when you type `/deploy`. Claude Code does not merge the two files and does not report a conflict; the command file is simply shadowed. This matters during a gradual migration: once the new skill folder exists, the old file stops being what runs, even though it is still on disk. Delete it once the skill is in place so nobody edits the wrong file. ## Migrating one command, step by step Migration is optional, but it is mechanical when you want the extra features: 1. Create a folder named after the command, for example `.claude/skills/deploy/`. 2. Move the file into it as `SKILL.md`; the frontmatter and body carry over unchanged. 3. Add any supporting files the instructions refer to, such as a runbook or a script, next to `SKILL.md`, and point to them from the body. 4. Delete the old `.claude/commands/deploy.md` so the shadowed copy cannot confuse a reviewer. 5. Type `/deploy` to confirm it still runs, and check `/skills` to see it listed. ## The same controls apply to both Because a command file is a skill in an older layout, the controls written for skills reach it too: - `disable-model-invocation: true` in a command file keeps Claude from starting it on its own, exactly as in `SKILL.md`. - The `disableSkillShellExecution` setting covers **skills and custom commands** alike, so injected shell lines in a command file are replaced by the policy placeholder when it is on. - A managed `allowManagedPermissionRulesOnly` setting makes Claude Code ignore `allowed-tools` in `.claude/commands/` files as well as in skill folders. Reviewers therefore read both folders the same way. A pre-approval or a shell line hidden in an old command file is as live as one in a new skill. ## Running either one However the file is laid out, you run it the same way: type `/name` **at the start of your message**, followed by any arguments, as in `/fix-issue 123`. Claude can also load a skill on its own when its description matches what you asked, unless the frontmatter turns that off with `disable-model-invocation: true`. The merge is why interviewers ask this question: a candidate who still describes commands and skills as two unrelated systems has learned an older Claude Code, and a candidate who thinks the old files stopped working may have rewritten a team's commands for no reason. ## Common misreadings - "Commands were deprecated and will stop loading." The docs say they keep working. - "The command file wins because it is older." The skill wins a name clash. - "A command file cannot take frontmatter." It takes the same fields except `name` and `paths`. - "Subfolders in `commands/` are ignored." They become colon-separated prefixes.

  • A repository has both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md. Which one runs when you type /deploy?
    The skill. When a skill and a file in `.claude/commands/` share a name, Claude Code runs the skill and the command file is shadowed. There is no merge and no conflict error, so after migrating you should delete the old file; otherwise someone may keep editing a file that never runs.
  • Which frontmatter fields does a command file not support, and what does that cost you?
    `name` and `paths`. Without `name`, the command name is always the file name. Without `paths`, you cannot limit automatic loading to files matching a glob. Everything else, such as `description`, `disable-model-invocation`, `arguments` and `allowed-tools`, works the same as in `SKILL.md`.
  • What command does .claude/commands/frontend/component.md create, and why?
    `/frontend:component`. For a command file in a subfolder, Claude Code takes the path relative to `commands/`, replaces each `/` with `:`, and appends the file name without its extension.

  • Custom commands were removed, so every .claude/commands file must be rewritten now.
  • When a command file and a skill share a name, the older command file wins.
  • A command file cannot carry frontmatter, so it cannot use disable-model-invocation.
  • A name field in a command file renames its slash command.
  • Skills and slash commands are separate systems with different invocation syntax.
open as a page

In a Claude Code SKILL.md, how do disable-model-invocation: true and user-invocable: false differ, and which keeps a /deploy skill from running on its own?

level: middleimportance: must knowfreq 27%

basics

~20 s

disable-model-invocation: true stops Claude invoking the skill and drops its description from context, while you can still type /deploy. user-invocable: false only hides it from you; Claude can still load it. /deploy needs the first.

open as a page

When you run /fix-issue 123 high in Claude Code, how do $ARGUMENTS, $0, $1 and named arguments in the skill's SKILL.md get filled?

level: middleimportance: should knowfreq 17%

basics

~20 s

$ARGUMENTS becomes the whole string as typed, $0 and $1 take the first and second shell-quoted words, and names declared in the arguments frontmatter map to positions in order. Input no placeholder receives is appended as ARGUMENTS: <value>.

open as a page

A Claude Code skill sets allowed-tools: Bash(gh *) in its frontmatter — what does that grant, for how long, and what does it not do?

level: seniorimportance: should knowfreq 12%

basics

~20 s

It pre-approves matching gh commands only during the turn that invokes the skill; the grant clears at your next message. It restricts no other tool, deny and ask rules still win, and workspace trust does not gate it.

open as a page

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%

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.

open as a page

In Claude Code, how do skillOverrides and a Skill(deploy) deny rule differ when you must keep Claude from invoking a shared repo's /deploy skill?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

skillOverrides changes what is listed: user-invocable-only hides /deploy from Claude while you can still type it, and off hides it everywhere. A Skill(deploy) deny rule is a permission rule that blocks Claude's Skill tool call itself.

open as a page