Ship Your Team's Shared Claude Code Workflows in One File: Custom Commands With .claude/commands/

TL;DR: A Markdown file in .claude/commands/ becomes a /command anyone on the team can invoke — commit it to the repo and every checkout gets the same repeatable workflow.

Claude Code ships with built-in commands like /compact and /review, but the most valuable ones are the ones you write yourself. Any .md file you drop in .claude/commands/ becomes a /command-name you can invoke from any Claude Code session in that project.

The format

.claude/commands/pr-review.md:

---
description: Security-focused PR review checklist
allowed-tools: Bash(git diff:*), Read
---

Review the current branch against main for security issues:

1. Run `git diff main...HEAD` to see all changes.
2. Check for: hardcoded credentials, SQL injection, XSS vectors, missing input validation, insecure dependencies.
3. Output a numbered checklist — ✅ safe / ⚠️ concern / ❌ blocker — with file:line references.

Focus on: $ARGUMENTS

Invoke it: /pr-review the auth and payment modules

The $ARGUMENTS placeholder injects whatever you type after the command name. Without it, Claude Code appends ARGUMENTS: <text> at the end — same effect, less control over placement.

Three patterns that pay off

/deploy-check — pre-push checklist: env vars set, migrations up, feature flags correct, tests green. Ten seconds instead of ten minutes of memory work.

/changelog [version] — generate a human-readable release summary from git log since the last tag, grouped by type and ready to paste into GitHub Releases.

/explain $ARGUMENTS — ask Claude to explain any symbol, pattern, or concept in the context of this specific codebase rather than in the abstract.

Scope and sharing

• .claude/commands/ — project-scoped, committed to the repo; everyone who checks it out gets the commands automatically.
• ~/.claude/commands/ — personal global commands, available in every project on your machine.

The YAML frontmatter is optional but earns its keep: description shows up in the command picker, and allowed-tools pre-authorizes the tools Claude needs so the run doesn't pause for permission prompts.

Sources: Commands — Claude Code Docs · Extend Claude with skills — Claude Code Docs · Claude Code cheatsheet 2026 — awesomeclaude.ai