Custom Commands in Claude Code

What custom commands actually are

Most people who discover Claude Code's slash commands stop at the built-ins: /clear, /compact, /resume. Those are session controls. Custom commands are something different. They're reusable workflow triggers you write yourself, stored as plain text, and invoked the same way as any built-in command.

The system is deliberately simple. You create a folder called .claude/commands/ inside your project directory. Every markdown file you put in that folder becomes a slash command. The filename becomes the command name. The contents of the file become the prompt Claude receives when you invoke it.

That's the entire mechanism. No configuration files, no syntax to learn beyond markdown. A file called weekly-status.md becomes /weekly-status. A file called client-handoff.md becomes /client-handoff.

The real value isn't the shortcut. It's that you've now encoded a repeatable workflow into something any team member, any collaborator, or your future self can invoke identically every time. The prompt doesn't drift. The output structure stays consistent. The same instruction runs against every client folder with the same precision.

> Folder structure at a glance > > `` > your-project/ > └── .claude/ > └── commands/ > ├── git-commit.md > ├── weekly-status.md > └── client-handoff.md > ``

Your first command in five minutes

Start with something you already do every session: committing changes with a meaningful message. Here's how to build a command that handles it for you.

Step 1: Create the folder structure.

mkdir -p .claude/commands

Step 2: Create your first command file.

touch .claude/commands/git-commit.md

Step 3: Write the prompt inside the file.

Open git-commit.md in any text editor and add this:

# git-commit

Review the current changes in this project, generate a clear and specific commit message that describes what changed and why, then commit those changes to the current branch.

The title at the top is optional but helps you remember what the command does when you're reading it later. Everything in the file gets sent to Claude as the prompt.

Step 4: Restart your session.

This is the one rule that trips people up. Claude Code reads the commands folder when a session starts. If you add or edit a command mid-session, it won't appear until you restart.

# Exit current session
/exit

# Start a new session
$ claude

Step 5: Invoke the command.

You: /git-commit

Tab autocomplete works here. Type /git and press Tab. Claude receives the full prompt from your file, reviews your uncommitted changes, writes a commit message, and executes the commit.

> What you just built: A one-keystroke git workflow. No more typing the same instruction every time. No more inconsistent commit messages across engagements. One command, always the same behavior.

The $ARGUMENTS placeholder

Static commands handle fixed workflows well. But most real work requires some input. The $ARGUMENTS placeholder solves this.

Add $ARGUMENTS anywhere inside your command file and Claude Code will inject whatever you type after the command name directly into that spot. The rest of the command stays exactly as written.

Here's a practical example. Create feature-plan.md:

# feature-plan

You are planning a new feature for this codebase. Read the relevant files to understand the current architecture, then produce a structured implementation plan.

The feature request is: $ARGUMENTS

Your plan should include: what files will change, what new files are needed, any dependencies to install, and the order of implementation steps. Do not write any code yet.

Now when you invoke it:

You: /feature-plan add export functionality for client reports

Claude receives the full command prompt, with $ARGUMENTS replaced by "add export functionality for client reports." The research instruction, the output format, the no-code constraint -- all of it carries through exactly as written.

This is where commands become genuinely powerful. You're not just saving keystrokes. You're enforcing a consistent research-before-code discipline every time you start on something new. The constraint lives in the command, not in your memory.

> One argument, not a form. $ARGUMENTS captures everything you type after the command name as a single string. Keep your input concise and specific. "Add client filtering to the dashboard" works. A 200-word specification does not.

Commands built for fractional work

If you're running two or three client engagements in parallel, the value of custom commands multiplies quickly. Here's what that looks like in practice.

Weekly status brief. A command that reads through the project's recent git history, open files, and any notes documents, then formats a structured status update ready to send to the client. You invoke it Friday afternoon. Claude pulls the context and produces a draft while you're finishing your last call.

Client handoff package. For when you're transitioning a project to another operator or to the client's internal team. The command reads the codebase, extracts decisions and rationale, and produces a structured document covering what was built, why it was built that way, and what's left to do.

Meeting recap formatter. Paste in raw notes after a client call. The command structures them into decisions made, action items with owners, and open questions. Same format every time, across every client.

Branch and PR workflow. If your team has specific naming conventions for branches or pull requests, encode them in a command. No more explaining the format to collaborators. They invoke the command, it creates the branch or PR with the right structure.

The more client engagements you run, the more these compound. A command written once runs identically against every project folder you point it at.

> Team use. Commit your .claude/commands/ folder to the project repository. Every person working in that codebase gets the same commands automatically. New team members onboard to your workflow standards on day one without a separate briefing.

One thing to know before you build a library

The .claude/ folder is intentionally hidden from Claude Code's file search. You cannot @-tag files inside it. You cannot ask Claude to "read my commands folder." This is by design: the commands folder is a system directory, not project content.

This creates one practical consideration. If you ask Claude to help you write a command prompt, you do it by specifying the path explicitly.

You: Write a feature planning prompt and save it to .claude/commands/feature-plan.md

Claude will navigate to the file directly, even though it doesn't appear in the normal file search. It works fine. It's just not browsable the same way your project files are.

The other rule: restart your session every time you add or edit a command. The commands load at session start. Mid-session edits don't take effect until you exit and return.

# Edit a command, then:
/exit
$ claude

# New command is now available
You: /your-new-command

These aren't limitations that require workarounds. They're just the two operational rules for the system. Know them and they won't slow you down.

> Start with one command. Pick the workflow you repeat most often this week, whether that's git commits, status reports, or meeting recaps. Write the prompt the way you'd explain it to a new colleague. Save it as a markdown file. Restart your session and try it. Build from there as patterns emerge in your own work.