Claude Code Custom Commands: 3 Practical Examples + When to (Not) Use Them
Understanding when to make Claude Code Custom Slash Commands, how to find useful ones online, and when to skip using this feature
Like any great developer tool, Claude Code is highly customizable, most notably through custom slash commands and custom output styles. But it might not be obvious when you should reach for these customization features.
This post will focus on custom slash commands by walking through three practical examples, sharing resources for finding more examples, and some guidelines on when to create custom commands and when not to use them.
What Is A Custom Command
Claude Code has many builtin slash commands such as /clear to empty the conversation, /context to view the context usage, /init to set up a CLAUDE.md, and /agents for managing subagents. Custom commands let us add our own special commands that similarly accomplish a common task with one quick word.
Custom commands live in either your home directory (~/.claude) and apply to all your sessions, or they can live in the ~/.claude directory in your project, thus enabling you to add the commands to a Git repo so they’re available to any other devs working on the project.
Custom commands are a bit like Bash scripts, but written in English instead of Bash. They can take arguments which can be accessed via the $ARGUMENTS flag or individually with $1, $2, $3, similar to Bash.
The most important insight is that custom slash commands are just prompts you save somewhere. This also creates a simple guideline:
Use a custom slash command for a long prompt that you frequently use
If we don’t frequently use a prompt, there’s not much value in saving it. If it’s something we do rarely, all the custom slash command does is obscure what the prompt is and make it harder to tweak it.
The reason we probably shouldn’t bother with custom commands for short prompts is we can simply type them in again. For example, if our prompt was very short like “do a git commit” or “review uncommitted changes”, then we could simply type those phrases.
However, both code commits and code reviews are examples of good places to build a custom slash command since those short phrases rarely capture the entirety of what you need in your development workflows, as we’ll explore next.
Example 1: Sanity Check On Git Commits
Paul Graham, founder of YCombinator, once wrote:
I was taught in college that one ought to figure out a program completely on paper before even going near a computer. I found that I did not program this way… I tended to just spew out code that was hopelessly broken, and gradually beat it into shape.
Like Paul, I often find myself writing code with a lot of exploratory work, commented out code, and TODO markers. However, I generally don’t want to check that code in.
Even more risky, sometimes when developing my apps I enable test flags or rig mock data so that I can test certain user flows. But it would be a critical mistake to commit that test code into production.
Historically, these problems were solved with tools like linters triggered by Git commit hooks and code review. Linters can only catch a small subset of issues, and code reviewers tend to find it annoying when they have to repeatedly view “sloppy” commits by the code author , which is perhaps not even available if you’re a solo dev. Plus, code review takes up valuable human time. LLMs to the rescue.
We can build a Claude Code /commit command that will first check for any TODOs, commented out code, test flags enabled, or anything that simply looks like it’s a temporary test change and commit only if those things don’t exist in the changeset.
I created the file ~/.claude/commands/commit.md and entered the following text:
Review all local modifications relative to HEAD, including both staged and unstaged changes.
Before committing, check for any of the following patterns:
TODO, FIXME, HACK, or similar developer notes.
Commented-out blocks of code.
Debugging or test flags left enabled (e.g., DEBUG = true, test_mode = 1, or console.log/print calls used for debugging).
Clearly temporary or experimental code (e.g., “temp”, “try”, “placeholder”, “test data”).
Hardcoded, rigged, or mocked logic used for testing — like forcing outcomes, overriding randomness, mocking API responses, or using fixed test data.
If any of these are found:
Abort the commit.
Output a clear, structured summary describing what was found and where, with short cleanup suggestions.
If none are found:
Stage all changes (git add -A).
Perform the commit using the following message: “ $ARGUMENTS “ , or if the previous arguments between the quotes are empty, read through the changes being committed and write an appropriate commit message that reflects the changes being made.
Output a short confirmation message indicating success (e.g., “✅ Commit completed — working tree clean.”).
As you can see, I use the $ARGUMENTS flag so that I can assign a commit message when using the command like /commit update the landing page, but I can also just type /commit and have Claude write a commit message for me based on the changes - pretty cool!
This custom command solves a huge pain point for me on solo projects as I always felt that double checking I didn’t accidentally commit some temporary testing code was a timesink. Claude is far smarter than a traditional linter and can understand changes that would otherwise never be flagged, as you can see by it being suspicious of this “hardcoded logic”, as seen in the following screenshot of my app development:
Besides sanity checking for TODOs or commented out code, there’s many other things you might want to review before you commit. For example, some people feel strongly that a commit should only do one thing, so that’s another condition you could add to the custom prompt.
Custom prompts are custom, so while you could use other people’s prompts verbatim, it’s worth considering massaging them to your specific workflows.
Example 2: Catchup Context After Context Clear
This next command is one that I’m borrowing from the blog post How I use Every Claude Code Feature by Shrivu Shankar which did extremely well on Hacker News (500+ upvotes).
Shrivu recommends having a /catchup custom command that reads in all the uncommited changes into your context. The idea is that you can call /clear as the context window gets full, then reload the necessary work-in-progress into your new conversation. It might look something like this:
“read all uncommitted git changes into this conversation“
Honestly, I’m on the fence about whether this is a great example of a custom Claude Code command because it falls a bit short of the “long” prompt qualifier I mentioned above. It’s not difficult to simply type . On the other hand, one word is shorter than eight if you’re doing it frequently.
I included this example for a few reasons anyway: first, I wanted to link to Shrivu’s excellent post; second, it’s an interesting example of managing the mechanics of Claude Code itself; and thirdly, it ties into very nicely into my third example.
Example 3: Catchup Context With Github Issues via MCP
I expect that for many people, the most useful custom commands will interact with MCP tools. Why? Because if a task exists that a general Claude Code user needs to do frequently, it’ll probably just get added to Claude Code builtin commands. Adding external tools is one of the ways Claude Code gets unique to you - thus needing customization - and external tools often require various forms of finagling that saved prompts can capture.
One of the most obviously useful MCP is the Github MCP. While you can already talk to Claude directly on Github as I wrote about in Scaling Claude Code with Github Actions, there’s still plenty of times you will want to be developing locally in Claude Code and want to access something on Github. Setting this up is fairly quick, you can create a GitHub personal access token and add the MCP to Claude Code as documented here.
Let’s tie this Github MCP concept with Example 2 of catching up on context after a /clear command. In example 2, we only added the code context. But often times, we don’t just want to know what the current code changes are, but why we’re making those changes, and those changes often exist in an issue tracker like Github Issues.
So now we can extend our /catchup command with something like this:
Find issue $ARGUMENTS on repo <your repo> and load its contents into the context here
Assuming you’ve installed the Github MCP, now you can pull all the information about the Github Issue into your conversation along with the code change after you run the /catchup command, resetting all necessary context after you cleared it. We could also consider pulling in information from relevant Pull Requests.
Where To Find More Examples
If you want to find more examples, you can check out the awesome-claude-code repo which has multiple examples of custom commands people have contributed. There’s a website directory at https://claudecodecommands.directory/ with more resources.
Browsing through there, we can look at several more templates of what people are using Custom Commands for:
Managing Git commits as demonstrated in Example 1
Context management tools as demonstrated in Example 2 and Example 3
Create documentation for new changes being added
Create a changelog.md or release notes based on recent commits or PRs
Managing releases
Creating formal product planning docs based on input docs
However, I would recommend avoiding using anyone else’s custom commands and instead use them for inspiration. After all, these are custom commands - it makes most sense to tailor them to your specific workflows. It’s also worth considering that if you add too many custom commands, you’re adding a level of indirection that might confuse new developers on a project if they have to learn dozens of project-specific command meanings.
Custom commands work best when they encode your specific workflows, and capture some sort of prompt you frequently find yourself reaching for but find tedious to repeatedly re-enter.
Thanks for reading and as always reply to this email or leave a comment on Substack.