- In short
- A Claude Code slash command is a reusable prompt stored as a markdown file. Put it in the project .claude/commands/ folder and it is committed and shared with the whole team; put it in your home ~/.claude/commands/ folder and it stays personal to you across every project. The file name (without .md) becomes the slash you type, so review.md is invoked as /review.
What Claude Code slash commands are
Claude code slash commands are reusable prompts you save once and trigger with a single keystroke sequence. Instead of retyping the same multi-line instruction every time you want a security review or a conventional-commit message, you write that instruction into a markdown file, and Claude Code turns the file into a command you call with a forward slash. The directory you save the file in decides one thing only, but it is the thing the Claude Certified Architect exam cares about: who else can use it.
- Slash command
- A markdown file stored under a commands directory whose body is a prompt. The file name without the .md extension becomes the command, so a file named review.md is invoked by typing /review in a Claude Code session.
The mechanics are deliberately plain. There is no registry to edit, no manifest to update, and no build step. You drop a file into a recognised folder, restart or refresh the session, and the command is live. Because the system is file-based, the question of scope reduces to a question of which folder, and that maps directly onto Claude Code three-level configuration model that you already met in the configuration hierarchy.
Where Claude Code slash commands live
There are two folders an architect must be able to name without hesitating, because the exam phrases its questions around the consequences of choosing the wrong one.
- Project commands,
.claude/commands/: this folder sits inside the repository. Anything you put here is version-controlled, so when a teammate clones or pulls the project they get the command automatically. This is the home for shared team workflows:/review,/release-notes,/migrate. - Personal commands,
~/.claude/commands/: this folder sits in your home directory, outside any project. Commands here follow you across every project on your machine, and they are invisible to everyone else because they were never committed to a repository.
The file name is the contract. A file at .claude/commands/review.md becomes /review; a file at ~/.claude/commands/scratch.md becomes /scratch. Use lowercase and hyphens for readable names, and avoid spaces. Creating the project folder is a one-liner: mkdir -p .claude/commands builds both the .claude parent and the commands child in a single step.
How the directory choice maps to sharing
Think of the two folders as two different blast radii. The project folder broadcasts a command to the team through git; the personal folder keeps it local. Nothing about the content of the markdown file changes between the two locations, which is exactly why the mistake is so easy to make and so hard to notice. A /deploy-preview command behaves identically wherever it lives, so the author sees it working perfectly and assumes everyone else does too.
Optional YAML frontmatter at the top of a command file refines its behaviour without changing where it lives: description sets the one-line label in the command picker, argument-hint shows the expected arguments during autocomplete, allowed-tools pre-approves a set of tools so the command runs without permission prompts, and model overrides the session model for that command. Inside the body, the $ARGUMENTS placeholder is replaced by whatever you type after the command name, so /fix-issue 123 feeds 123 straight into the prompt.
The anatomy of a command file
A command file is plain markdown, and the body is simply the prompt Claude runs when you invoke it. But the optional frontmatter at the top is what turns a throwaway snippet into a polished, reusable tool, so it is worth knowing the fields you are most likely to see in an exam stem.
descriptionwrites the one-line label shown in the command picker, which helps you and your teammates remember what each command does at a glance.argument-hintdisplays placeholder text during autocomplete, such as[issue-number]or[file] [format], so anyone invoking the command knows what to type after the name.allowed-toolslists tools the command may use without stopping to ask for permission, which keeps a trusted workflow from interrupting you with approval prompts on every step.modeloverrides the session model just for that command, useful when a particular workflow benefits from a faster or more capable model than your default.
Inside the body, argument placeholders make a command dynamic. $ARGUMENTS is replaced by everything you type after the command name, so /fix-issue 123 feeds 123 straight into the prompt. For finer control, $1 and $2 (shorthand for $ARGUMENTS[0] and $ARGUMENTS[1]) pull individual positional arguments, so a /migrate-component SearchBar React Vue command can address each value separately. There is even a dynamic-context form: a line beginning with !`command` runs that shell command first and inlines its output before Claude reads the prompt, so a command can arrive pre-loaded with a live git diff or test result. None of this changes the project-versus-personal rule; it just makes each command richer wherever it lives.
How Claude Code discovers your commands
Discovery is automatic and folder-based, which is why the two directories are the whole story. When a session starts, Claude Code scans the project .claude/commands/ folder in your working directory and in every parent directory up to the repository root, so a command defined at the repo root is still available when you launch a session from a deep subdirectory. It also scans your personal ~/.claude/commands/ folder so your private helpers come along to every project. Each markdown file it finds becomes a command named after the file, minus the .md extension.
Two discovery details occasionally surface in questions. First, live change detection means adding or editing a command file usually takes effect within the running session, so you rarely need to restart to pick up a new command. Second, commands and skills now share a namespace: if a .claude/commands/deploy.md file and a .claude/skills/deploy/SKILL.md skill both define /deploy, the skill takes precedence. That precedence rarely bites in practice, but it explains why a command can appear to be overridden when a same-named skill exists in the project.
A checklist for placing a new command
When you create a command, decide its home with one question and a quick sanity check.
- Should every teammate have this? If yes, it is a project command: put it in
.claude/commands/and commit it so git distributes it. If it is just for you, it is a personal command in~/.claude/commands/. - Does the name read cleanly as a slash command? Use lowercase and hyphens, and confirm the file name is exactly the command you want to type.
- Did you actually commit it? The most common failure is a shared command authored in the project folder but never committed, which leaves teammates without it just as surely as saving it personally would. A quick
git statusbefore you move on closes that gap.
This three-step habit is enough to avoid every scoping mistake the exam tests for this knowledge point.
How commands relate to skills
Recent Claude Code versions merged custom commands into the broader skills system. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way when you invoke them by hand. Your existing .claude/commands/ files keep working untouched, so the project-versus-personal directory rule you are learning here is still exactly right. What skills add on top is a folder for supporting files, richer frontmatter, and the ability for Claude to load the procedure automatically when it is relevant rather than only when you type the slash. For the foundations exam, anchor on the directory split first; the skill upgrades build on it.
Worked example
A team lead writes a /security-scan command that runs a consistent vulnerability checklist. A new engineer clones the repo, types /security-scan, and Claude Code says the command does not exist.
The lead built the command while iterating in their own checkout and, out of habit, saved it to ~/.claude/commands/security-scan.md. On the lead machine it works flawlessly, which is precisely why the problem hides. That folder is the personal location: it lives in the lead home directory and was never part of any commit. When the new engineer pulled the repository, they received every tracked file, but the command was not one of them, because it was never tracked in the first place.
The fix is a move, not a rewrite. Relocate the file to .claude/commands/security-scan.md inside the repository, commit it, and push. The next time any teammate pulls, /security-scan appears for them automatically. Nothing about the prompt body changes; the only edit is the directory, which flips the command from personal to shared. This is the single most testable fact about command structure: a shared workflow belongs in the project folder so that version control distributes it, and a one-off personal helper belongs in the home folder so it does not clutter everyone else session.
Common misreadings to avoid
Misconception
If I save a slash command on my machine, my teammates can use it too once they pull the repo.
What's actually true
Misconception
You have to register a slash command in a settings file before Claude Code will recognise it.
What's actually true
How this shows up on the exam
Domain 3 is worth 20% of the exam, and TS 3.2 asks you to create and configure custom slash commands and skills. Questions about command structure almost never ask you to recite a path in the abstract. Instead they hand you Scenario 2 (code generation with Claude Code) or Scenario 4 (developer productivity) and describe a symptom: one developer has a command, another does not; a workflow that was supposed to standardise the team behaves inconsistently; a freshly onboarded engineer is missing tooling everyone assumed was shared. The correct answer almost always traces to scope. A command that should be shared was saved personally, or a personal experiment was committed and now pollutes the team. Hold the two folders and their blast radii in mind and these questions resolve quickly. From here, the natural next step is understanding how skills extend a command with SKILL.md and frontmatter.
Your team standardises pull-request descriptions with a /pr-summary command. You created it months ago and use it daily. A teammate on the same repository reports that typing /pr-summary does nothing for them. What is the most likely root cause?
People also ask
Where do Claude Code slash commands live?
What is the difference between .claude/commands and ~/.claude/commands?
How do I create a custom slash command in Claude Code?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Custom commands
Why watch: Authoring slash commands and choosing project versus personal scope is exactly the commands-directory structure this KP defines.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.