Claude Code Custom Slash Commands: Standardize Team Tasks

Claude Code Custom Slash Commands: Standardize Team Tasks

Custom slash commands in Claude Code are Markdown files stored in the .claude/commands folder of your repository. Each file becomes a command that anyone on the team can run by typing a slash and its name. Because the file is versioned alongside the code, repeated tasks such as code review, release notes and testing get a single playbook, reviewed through a pull request. Use a command when a person decides when to run the task. Use a skill when you want Claude to pick the procedure on its own based on context.

Key takeaways

• A slash command is a Markdown file with instructions. The file name becomes the command name.
• Keeping commands in the repository (.claude/commands) means the whole team uses the same playbook, with history and change review.
• Commands suit tasks a human triggers on purpose. Skills suit knowledge Claude should apply when it notices it is relevant.
• Limit the tools each command can use: a review only needs to read, release notes need to read history, and tests need to run one specific command.
• Start with one command in one real workflow, then decide after a few weeks whether to expand, adjust or drop it.

What is a custom slash command in Claude Code?

Claude Code ships with built-in commands for managing the session. On top of those, you can create your own. A custom command is a prompt you wrote once, saved to a file and now call by name, instead of retyping the request each time with slightly different wording.

There are two common places for these files:

• The .claude/commands folder inside the project: the command is available to anyone who clones the repository and travels with the code.
• The .claude/commands folder in the user's home directory: the command is yours alone, across all projects.

For team standardization, the first location is the one that matters. The gain is not saved keystrokes. The gain is that the instruction stops living in one person's head or in a chat thread and becomes an engineering artifact: it can be read, questioned, improved and reverted.

The exact syntax changes between Claude Code versions. Before adopting any detail in this article, check the official documentation for the version your team uses. What follows is the general pattern: a Markdown file, a metadata block at the top (frontmatter) and a body with the instructions.

How to create your first versioned command, step by step

This is a short plan designed for one technical person and one operations person working together.

• Pick a task the team repeats every week and that each person currently does differently. Pull request review is a good candidate.
• Write down, in plain language, what a good result contains. What does the reviewer always check? What should never be suggested? Which response format helps the reader?
• Create the file inside .claude/commands with a short, clear name, for example review.md. The command is then called as /review.
• At the top, fill in the command description. When your version supports it, also set the allowed tools and an argument hint, so whoever types the command knows what to provide.
• In the body, write the instructions. If the command takes a parameter (a pull request number, a folder name), use the argument placeholder described in the documentation.
• Test it on two or three real cases, including a hard one. Adjust the text until the output is stable.
• Open a pull request with the file. Reviewing the command is part of the process, like any other code change.
• Tell the team and record in the README what the command does and what it does not do.

Two features are often useful, as long as your version supports them: running a shell command before the prompt to inject context (for example, the list of changed files) and referencing repository files directly in the text. Both reduce how much people must paste by hand, which also reduces mistakes. On the context side, the lesson from Anthropic's material on effective context engineering for AI agents applies: provide the minimum relevant information, not everything that exists.

Which tasks deserve a command: review, release notes and tests

Not every task deserves a command. The best ones share three traits: they happen often, they have an expected output format, and they depend on context that lives in the repository itself.

Code review commands

The review command tells Claude to look at the difference between the current branch and the main branch, and to answer in fixed categories: bug risk, security, readability, test coverage. It is worth writing what it must not do as well: not rewrite the file, not approve anything, not comment on style the linter already covers. The output is a draft for the human reviewer, not a decision.

Release notes commands

The command reads the changes since the last version and drafts text for the right audience. The audience is the critical point here: release notes for people who use the product differ from a technical changelog. Define the tone and the language in the command (Brazilian Portuguese, for example), plus the rule that each item must point to a real change, with no invented features. The person responsible for the release reads and corrects the draft before publishing.

Test commands

The test command asks Claude to run the agreed suite, explain failures and propose a fix or new cases for the changed code. Allow only the agreed test command, not free shell execution. On trusting what gets generated, read how to validate AI-generated tests: a passing test is not the same as a test that protects you.

Illustrative scenario

Imagine a small software team that supports a chain of retail stores. Today each developer asks Claude for a review in a different way, and the answers range from thorough to superficial. The team creates a /review command with five fixed categories and one rule: point to the file and line, and separate what is certain from what is suspected. On each pull request, the author runs the command and pastes the result into the description, and the human reviewer uses it as a starting point. Two months later, someone proposes, through a pull request, adding a category on personal data, because the team noticed logs were exposing customer phone numbers. The change is discussed, approved and applies to everyone. That is the effect of versioning: the practice visibly improves.

Command or skill: how to decide

The central question is who triggers it. With a command, the person does: they type the slash and the name. With a skill, Claude reads the description and decides to use it when the task in progress matches. To understand the other side, see what skills are in Claude Code and how to build them for your team.

A decision guide in list form:

• Use a command when the task has a clear trigger moment, such as before opening a pull request or when closing a release.
• Use a command when you want predictability: same input, same playbook, with no Claude judgment about whether to apply it.
• Use a skill when the knowledge should apply across many conversations and Claude needs to recognize the situation on its own, such as project naming conventions or rules for an internal API.
• Use a skill when the procedure involves several supporting files, such as templates, examples and scripts, that should not occupy context all the time.
• Use both when it makes sense: a command that starts the flow and a skill that holds the detailed rules it consults.
• When in doubt, start with a command. It is simpler to understand, to test and to explain to someone joining the team.

An honest note: depending on the version, the official documentation treats commands and skills quite closely, and older files in .claude/commands keep working. The practical distinction, who triggers it and how much supporting material exists, is still useful for deciding. Check the documentation for what changes in your installation.

How to limit what a command can do

A standardized command also standardizes risk. A playbook that runs unrestricted shell commands, written in a hurry, replicates the problem across the whole team. That is why setting limits is part of the design, not an afterthought.

• Allow only the tools that are needed. A review command reads files and history. It does not need to write anything. This follows the principle of least privilege described in guides such as the OWASP Authorization Cheat Sheet.
• Write what is forbidden into the command itself: no pushing, no deleting files, no touching configuration files that hold secrets.
• If the command uses external integrations, treat them carefully. The article on configuring MCP in Claude Code explains local, project and user scopes, which matter when a command depends on a connected tool.
• Remember that content the command reads (pull request descriptions, comments, third-party files) may contain malicious instructions. Reviews and release notes read text that other people wrote.
• Keep personal data out of the flow. If the repository contains customer data, Brazil's data protection law (LGPD) calls for caution about what is sent to an external service. See what the law requires in international data transfer when using AI providers.

The logic is the same one argued in Anthropic's material on building effective agents: start with the simplest flow that solves the problem and increase autonomy only when there is a reason and a way to observe the result.

How to pilot, measure and hand over to the team

The method we use for any AI adoption applies here, at small scale: map, limit, pilot and hand over.

• Map: describe how the task is done today, who does it, how long it takes and where people differ. Without this starting point, no one will know whether the command helped.
• Limit: define the allowed tools, the data that may go in and what the command never does.
• Pilot: put a single command into real use with a small group, and agree beforehand on which signal counts as success. It can be qualitative: do reviewers find the draft useful? Do release notes need less correction?
• Hand over: document it, name an owner for the file and decide together whether to expand, adjust or retire it.

On measuring, avoid turning the command into a tool for monitoring individuals. The goal is to improve the process, not to rank people. The article on measuring AI productivity without surveillance covers that balance.

To keep the collection healthy, a simple routine helps:

• One owner per command, named in the file.
• A quarterly review: is the command still used? Does it still reflect the process?
• Removal, without ceremony, of commands nobody calls.
• Consistent names, in Portuguese or in English, but not mixed.
• A list in the README with a one-line description of each command.

Frequently asked questions

Where do custom slash commands live, and how does the team get them?

Project commands live in the .claude/commands folder inside the repository, and anyone who clones or updates the code receives the files with it. Personal commands live in the user's home directory and are not shared. For team standardization, use the repository and route changes through pull requests.

Do I need to know how to code to create a command?

Not to write the file, which is Markdown text with clear instructions. But whoever creates it should understand the process being standardized and, if the command runs something in the terminal, get help from a technical colleague to set the limits. For beginners, the guide on Claude Code for non-programmers is a good starting point.

When should I replace a command with a skill?

Switch when you notice people forget to call the command, or when the procedure starts to depend on many supporting files and rules that Claude should apply on its own. If the manual trigger is part of the process, as when closing a release, the command remains the clearer choice.

Can the command's output be published without review?

It is not recommended. The command standardizes the playbook but does not guarantee the output is correct. Reviews, release notes and generated tests should pass through a responsible person before becoming a decision, a publication or code in production.

Sources

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• OWASP: Authorization Cheat Sheet