Custom commands

You find yourself typing the same "please audit the dependencies, check for vulnerable packages, fix them, and run the tests to make sure nothing broke" prompt for the third time this week. That is a custom command waiting to happen. Custom commands turn repeated workflows into one-line slash commands — and they are just markdown files.

A custom command is a markdown file in .claude/commands/ that becomes a slash command. Filename becomes command name. File contents become the instructions Claude executes when you run it.

Step 1 — Create the commands directory

Inside your project root, make the directory:

mkdir -p .claude/commands

This is where every custom command for this project lives. You commit it to source control if you want the whole team to share the commands, or gitignore it if they are personal.

Step 2 — Build a command by writing a markdown file

Create .claude/commands/audit.md with the instructions you want Claude to follow:

Run `npm audit` and identify any vulnerable packages.

For each vulnerable package:
1. Check if a non-breaking fix is available.
2. Apply the fix.
3. Run the test suite to confirm nothing regressed.

Report what you fixed and any packages that still need attention.

That is the entire command. Save the file.

Step 3 — Restart Claude Code

Custom commands are loaded at startup. Restart Claude Code in the project directory, and the command becomes available.

Step 4 — Run the command

Invoke it like any other slash command:

/audit

Claude reads the markdown contents and executes the instructions. Same tool use, same workflow — just kicked off with two keystrokes instead of a paragraph of prose.

Step 5 — Accept parameters with $ARGUMENTS

Commands can take runtime parameters using the $ARGUMENTS placeholder. Anything you type after the command name replaces $ARGUMENTS in the file contents.

Create .claude/commands/write_test.md:

Write unit tests for the file at $ARGUMENTS.

Follow the testing conventions in CLAUDE.md. Cover the happy path plus
at least one edge case per exported function. Put the tests next to the
source file.

Now you can run:

/write_test src/auth/login.ts

And $ARGUMENTS becomes src/auth/login.ts inside the prompt Claude receives. Arguments can be anything — file paths, symbol names, descriptive text — whatever the instructions expect.

When to reach for a custom command

If you have typed roughly the same prompt more than twice, write the command. The ROI is immediate because you never again pay the cost of re-explaining the workflow.

Commit useful commands to the team's .claude/commands/ directory. That way, when a new teammate joins, they get /audit, /write_test, and anything else you have built as first-class project tooling.