D3 · Claude Code › Cluster 4 · Slash Commands

4.2 · Custom Slash Commands

.claude/commands/*.md

CONCEPT A Markdown file becomes a /command

A custom slash command is just a Markdown file whose body is a prompt template. Drop deploy.md into .claude/commands/ and Claude Code exposes /deploy. The filename without its extension is the command name. When you invoke it, the file's body (after argument and injection substitution — see 4.4) is sent to the model as your message.

🔑 In current Claude Code, custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Existing .claude/commands/ files keep working and support the same frontmatter; skills add extras (a folder for supporting files, auto-invocation). If a skill and a command share a name, the skill takes precedence.

LocationPathScope
Project.claude/commands/<name>.mdThis repo only (commit it to share)
Personal~/.claude/commands/<name>.mdAll of your projects

CONCEPT Subdirectories create namespaces

Put a command in a subfolder and the folder becomes a namespace shown in the command's listing. A file at .claude/commands/frontend/component.md is still invoked as /component, but the menu shows it grouped under frontend so you can tell same-named commands apart. Namespacing is organizational; it does not change how you type the command.

Give a project command a clear, task-shaped name — /fix-issue, /write-tests, /review-pr — and one job. A custom command is your team's reusable, version-controlled prompt.

DIAGRAM From file on disk to a running prompt

flowchart TD F[".claude/commands/fix-issue.md"] --> D["Claude Code discovers it at startup"] D --> M["Appears in the / menu as /fix-issue"] M --> I["You type: /fix-issue 123"] I --> S["Body is expanded:
args, !bash, @file substituted"] S --> P["🟢 Rendered prompt sent to the model"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef step fill:#cfe2ff,stroke:#0d6efd,color:#084298; class P ok; class S step;

CODE Create a project command and invoke it

Two files, two scopes. The body is plain Markdown; $ARGUMENTS is replaced with whatever you type after the command name (covered in 4.4).

# A project command — lives with the repo, shared with the team
$ mkdir -p .claude/commands
$ cat > .claude/commands/fix-issue.md <<'EOF'
Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit
EOF

# A namespaced command — menu groups it under "frontend"
$ mkdir -p .claude/commands/frontend
$ echo "Create a React component named $ARGUMENTS." \
    > .claude/commands/frontend/component.md

# Then, inside Claude Code:
#   /fix-issue 123     → runs the project template with 123
#   /component Button  → runs the namespaced command

TRADE-OFFS Project command vs. personal command

✅ Project — .claude/commands/

  • Committed to the repo, shared with everyone
  • Encodes team workflows and conventions
  • Travels with a clone; consistent for all contributors
  • Subject to workspace trust before its tools run

✅ Personal — ~/.claude/commands/

  • Available across all your projects
  • Private to you — not committed anywhere
  • Great for personal shortcuts and habits
  • Not shared, so teammates won't have it
🔑 Both are the same mechanism — a .md file invoked as /name. Only the directory (project vs home) decides the scope. See 4.5 for the full scope story.

EXAM TRAPS

Trap: "The command name comes from frontmatter." → For a .claude/commands/ file the name is the filename without extension. (Skill directories take their name from the directory.)
Trap: "A subdirectory changes how I invoke the command." → No. A subfolder only adds a namespace label in the menu. frontend/component.md is still /component.
Trap: "Custom commands are a separate feature from skills." → They have been merged. A command file and a same-named skill both create the same /name; if both exist, the skill wins.
Trap: "Project commands need to be under src/ or the repo root only." → They are discovered from .claude/commands/ at (and up to) the repo root. Personal ones live in ~/.claude/commands/.

PRACTICE

Q1 · What file creates the command /deploy, and where for team-wide use?

A Markdown file named deploy.md. For team-wide use put it at .claude/commands/deploy.md and commit it. For personal-only use, ~/.claude/commands/deploy.md.

Q2 · How do you invoke .claude/commands/git/commit.md?

As /commit. The git/ subdirectory only adds a namespace label in the menu; it does not become part of what you type.

Q3 · A skill deploy and a command deploy.md both exist. What runs on /deploy?

The skill — when a skill and a command share a name, the skill takes precedence. Both still map to the same /deploy command name.