Claude Code’s .claude/commands: Build reusable slash commands for reviews, tests, deploy checks, and changelogs
Claude Code’s .claude/commands enable custom slash commands, turning repeat prompts into repo-backed tools for code review, tests, deploy checks, changelogs.
Claude Code quietly includes a powerful, developer-facing feature that often goes unnoticed: a repository folder called .claude/commands where you can define custom slash commands to run inside any Claude Code session. These custom slash commands let teams capture repeatable prompt workflows — everything from a consistent code-review checklist to test scaffolding and pre-deploy checks — as plain files in the repo so every developer inherits the same workflow on git clone. The result is a lightweight, version-controlled way to convert recurring prompts into first-class developer tools that integrate with code review, testing, and release routines.
What custom slash commands are and why they matter
Custom slash commands in Claude Code function like prompt aliases: short, typed triggers (for example /review or /test) that expand into a full instruction or prompt template when invoked. By storing those templates in a .claude/commands directory inside your project, you make them part of the codebase — visible, reviewable, and versioned with the rest of your source. That changes how teams use LLMs day to day: rather than each engineer maintaining their own private prompts, the project carries a shared set of vetted workflows. This reduces variability, accelerates onboarding, and helps enforce standards for security, testing, and release hygiene.
How to define a slash command in .claude/commands
At its simplest, a slash command is a markdown file inside .claude/commands. The filename (without extension) becomes the command name. For instance, a file named review.md maps to /review. The file body is the prompt template Claude will execute when you run the command. You can include instructions, checklists, formatting rules, and placeholders for arguments — anything that codifies the behavior you want from the model.
A typical workflow:
- Create a .claude/commands folder in the repository root.
- Add a markdown file per command; use clear filenames like review.md, test.md, deploy-check.md.
- Commit the folder so it travels with the repo and is available to every collaborator.
Because the commands are files in source control, teams can review changes to the prompts, associate updates with PRs, and roll back if needed — an important capability for disciplined engineering organizations relying on LLMs in their pipeline.
A practical command set that developers use daily
Teams commonly capture several recurring development tasks as slash commands. Representative examples include:
-
/review — a concise, consistent code-review checklist that instructs Claude to look for security issues, performance regressions, missing tests, and style violations, and to format output into categorized buckets (Critical, Warnings, Suggestions).
-
/test — a template that asks Claude to generate comprehensive unit and integration tests for pasted code, using the project’s test stack (for example Jest + Testing Library), mocking external dependencies and targeting branch coverage goals.
-
/deploy-check — a pre-deployment verification script that inspects diffs for hardcoded secrets, leftover debugging statements, TODOs, migration requirements, and breaking API changes; it returns actionable file:line locations and remediation advice.
- /changelog — a prompt that converts pasted git log output into user-facing changelog lines grouped by Features, Bug Fixes, Performance, and Breaking Changes, written in present tense and free of internal ticket noise.
Each of these command templates can be tailored to your repository’s conventions: reference your ESLint configuration, your preferred testing frameworks, or your release notes style. Because the templates live in the repo, they evolve with the project.
How to pass arguments and make commands dynamic
Slash commands can accept inline arguments: what you type after the command name is substituted into the template (often represented by $ARGUMENTS or a similar placeholder). That makes a single command versatile. For example, a fix-bug.md command might contain a short instruction like “Fix the bug described here: $ARGUMENTS” and then a structured approach: explain cause, propose a minimal fix, explain why it works, and suggest a regression test. To use it you would type something like:
/fix-bug TypeError: Cannot read property ‘id’ of undefined in UserProfile.jsx:34
The command receives the description and Claude generates a targeted response. Combined with clipboard paste of code snippets or git diffs, this approach lets engineers get precise, contextual assistance without retyping the same prompts every time.
Team commands versus personal commands: controlling scope and discoverability
Storing commands in .claude/commands makes them part of the project and visible to the team; that’s ideal for shared practices like /review and /deploy-check. For personal workflows that you don’t want to commit, Claude Code also supports a global directory (for example ~/.claude/commands) that the local user owns. Use the repo-level folder for standardized, team-wide operations and the global folder for one-off utilities or private debugging workflows. This dual approach balances consistency and personal productivity.
An example repository layout that captures the workflow
A recommended layout to make the most of Claude Code slash commands is straightforward: keep settings and project context files in .claude at the repo root, and add a commands subfolder that contains a short markdown file for each command. That keeps tool permissions, project context, and command templates co-located with code and documentation so new team members get the same setup when they clone the project.
Permissions, project context, and CLAUDE.md
Alongside commands, include a .claude/settings.json to control tool permissions and a CLAUDE.md (or similar) file with context the model should use, such as tech stack, coding conventions, and security policies. These files help the model produce responses aligned with your codebase and constraints. Because these artifacts are in the repo, they form part of the project’s operational configuration and are subject to the same review and change control as code.
Practical questions answered: what it does, how it works, who benefits, and availability
What it does: Custom slash commands transform repeated, human-written prompt instructions into reusable, versioned templates you can invoke inside a Claude Code session.
How it works: Command files are simple markdown documents placed in .claude/commands; the filename becomes the slash command and the file contents are the prompt template. Commands can accept arguments typed after the command name and can be combined with pasted diffs or code for context.
Why it matters: By making prompts part of the repository, teams reduce variability in outputs, accelerate onboarding, and capture best practices for reviews, testing, release notes, and other routine tasks. It creates a single source of truth for LLM-powered workflows.
Who can use it: Any developer using Claude Code can benefit — from individual contributors who want consistent tool-assisted reviews to engineering managers who want enforceable standards embedded in the repo. Organizations that emphasize reproducibility, security reviews, and test coverage will find particular value.
When it’s available: The mechanism described is local to Claude Code and operates whenever you have the local CLI or editor integration enabled and the .claude folder present in your project. Commands stored in the repo are automatically available to collaborators after git clone and any setup required by your Claude Code integration.
Security, compliance, and operational concerns
Embedding prompts in source control raises a few operational considerations. First, never hardcode secrets into command templates — don’t put API keys, credentials, or private tokens in files that will be committed. Use environment variables or secure secret stores instead. Second, make sure your CLAUDE.md project context doesn’t include proprietary data that shouldn’t be exposed to the model; sanitize or redact internal-only details.
When using the model to scan diffs or identify secrets, treat its suggestions as triage-level: it can flag likely problems but should not replace programmatic secret scanning tools or formal security reviews. Combine LLM-driven checks with automated linters, SAST/DAST tools, and CI policies for a layered defense.
Cost implications and API routing strategies
Heavy use of Claude Code, particularly workflows that paste large diffs or repeatedly run review/test generation commands, can consume API tokens quickly. Some teams reduce costs by routing requests through API proxies or third-party services that re-bill at different rates. If you adopt such a proxy, configure it in your Claude Code settings (apiKey and baseURL) following security best practices: limit scope, rotate keys regularly, and audit usage.
Be mindful that proxies change the trust boundary. Validate their privacy and security policies before routing production data through them. For cost-conscious teams, optimize command templates to avoid unnecessary verbosity in prompts and reuse context files rather than pasting large amounts of code where possible.
Integration points with developer toolchains
Slash commands map naturally to several parts of modern developer toolchains:
- Code review: Use /review as a first-pass assistant for security and performance checks, then rely on human reviewers for judgment calls.
- Testing: /test can scaffold unit tests and a testing recipe you paste into PRs or CI jobs.
- CI/CD: Run /deploy-check locally before opening a release PR, or incorporate command-driven checks as scripted steps that generate artifacts reviewers can inspect.
- Release engineering: Run /changelog against git logs to produce user-facing release notes that can be copied into release platforms or product changelogs.
These integrations make the LLM a copilote embedded in existing workflows rather than an external, ad-hoc tool.
Governance and maintenance of command collections
Because commands are versioned, they should be treated like code. Establish a small set of guidelines:
- Maintain a short CLAUDE.md documenting each command’s purpose and expected usage.
- Review changes to command files in PRs, especially those that alter security, testing, or release behaviors.
- Limit who can modify sensitive prompts; use code owners or protected branches if necessary.
- Periodically audit commands for stale or redundant templates and remove or consolidate as the codebase evolves.
This governance prevents a proliferation of overlapping prompts and keeps the command set aligned with team standards.
Developer experience and onboarding benefits
Making repeat prompts available in the repo smooths new-hire onboarding: instead of relying on tribal knowledge, new developers find a ready set of curated prompts for reviews, testing, and releases. It also standardizes how the team asks the model to behave, reducing inconsistent outputs and making model responses more predictable.
For individual contributors, personal command files in a home directory still allow experimentation. Encourage sharing of high-quality personal commands by migrating them into the repo as needed, with review and context added.
Broader implications for software teams and businesses
Embedding LLM-driven routines as code artifacts shifts how organizations operationalize AI-assisted development. It moves prompt management from individual notes and chat transcripts into the same lifecycle as source code: reviewable, version-controlled, and auditable. That change has multiple implications:
- Developer productivity: Routine tasks become faster and more consistent, freeing engineers for higher-leverage work.
- Quality and compliance: Shared templates enforce minimum standards for security checks, test generation, and changelog quality, reducing regressions.
- Vendor and cost management: Centralizing prompts highlights consumption patterns, making cost optimization and routing decisions more straightforward.
- Auditability: Because command files are committed, teams can trace when a prompt changed and why, a helpful property for regulated environments.
This pattern also nudges organizations to think of prompts as part of their operational configuration, akin to linting rules or CI configuration, which should be managed with similar discipline.
Best practices for writing robust command templates
- Be explicit about scope: Tell the model which code style, frameworks, and security rules to assume.
- Keep outputs structured: Ask for categorized lists (Critical, Warnings, Suggestions) and include file:line reporting when checking diffs.
- Limit context size: Prefer pasting focused diffs or files rather than entire repositories; use CLAUDE.md for persistent context.
- Include examples: For complex tasks, an example input/output pair in the command file helps align expectations.
- Version prompts intentionally: Tag major changes in templates with a short header describing the rationale so reviewers understand the impact.
When to rely on Claude and when to use traditional tools
LLMs are excellent at pattern recognition, summarization, and drafting test scaffolds, but they are not a substitute for deterministic tooling. Use Claude-driven commands for triage, drafting, and human augmentation — and retain linters, static analysis, secret scanners, and CI gates for enforcement. The ideal is complementary: Claude accelerates humans, and programmatic tools enforce correctness.
Real-world adoption: a typical team workflow
A typical flow might look like this:
- Developer runs /deploy-check locally on a prepared git diff. The command flags a potential hardcoded key.
- Developer fixes the issue, commits, and pushes a PR.
- As part of the PR template, the developer pastes failing tests and runs /test to generate additional unit tests for an uncovered edge case.
- The reviewer uses /review to verify the PR addresses performance and security concerns, and annotates any remaining items.
- At release time, the release engineer runs /changelog with a pasted git log excerpt to produce user-facing release notes.
Because these commands are in the repo, the team iterates on them — improving /review checklists and /test scaffolds as the codebase and risk profile evolve.
Looking ahead, command collections can be extended to include prompts that integrate with observability data, security alerts, or customer support tickets, further embedding LLMs into the end-to-end software lifecycle. As organizations gain experience, expect to see curated prompt libraries, centralized governance policies, and CI hooks that call repository-backed commands as part of automated checks. These trends will push teams to treat prompts as maintainable infrastructure: versioned, reviewed, and optimized for cost and privacy constraints.
