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.
.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.| Location | Path | Scope |
|---|---|---|
| Project | .claude/commands/<name>.md | This repo only (commit it to share) |
| Personal | ~/.claude/commands/<name>.md | All 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.
/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
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
.md file invoked as /name.
Only the directory (project vs home) decides the scope. See 4.5 for the full scope story.EXAM TRAPS
.claude/commands/ file the name is the filename without extension. (Skill directories take
their name from the directory.)frontend/component.md is still /component./name; if both exist,
the skill wins.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.