Organizing Project vs Personal Commands

Once you start writing custom commands, a question comes up: should this command be shared with everyone on the project, or is it just for you? Claude Code answers this with two locations, and choosing the right one keeps things tidy.

Two homes for commands

Project commands live inside the repo:

.claude/commands/*.md

Personal commands live in your home folder:

~/.claude/commands/*.md

Both work the same way — the filename becomes the command name, the body is the prompt, and the same frontmatter and $ARGUMENTS rules apply. The only difference is who gets them.

When to use each

Put it in the project folder when the command is about this codebase and the whole team benefits. Because .claude/commands/ sits in the repo, it's checked into git and everyone who clones the project gets the command for free. Good candidates:

• A changelog generator tuned to your commit style.
• A review command that knows your project's conventions.
• Scaffolding that follows your team's file layout.

Put it in your home folder when it's a personal habit that follows you across every project. Good candidates:

• Your own explain-this-code shortcut.
• A personal commit-message helper.
• Quick utilities you like regardless of the repo.

A simple test

Ask: would a teammate want this, and does it depend on this project? If yes to both, it's a project command — commit it so the team shares it. If it's your personal workflow, keep it in ~/.claude/commands/ so it travels with you and doesn't clutter the repo. Sorting commands by this rule keeps each project's command list meaningful and your personal toolkit always at hand.