Wes Ellis./ a personal notebook
Technology. Stories. Side projects.
A few things worth writing down.
SearchSubscribe
← Back to Engineering

Engineering

Custom Slash Commands Worth Keeping

By Wes Ellis4 min read
A gray mechanical keyboard with one orange key, on a wooden desk.

Part 3 of the thread Building with Claude and MCP

THE SHORT VERSION4 points
  • A slash command is a Markdown file of instructions you run by typing / and its name.
  • Files in .claude/commands/ still work, but the docs now treat them as the older form of skills.
  • Arguments come in through $ARGUMENTS, and $0 is the first one now, not $1.
  • A command earns its place when you've typed the same prompt more than a couple of times.

My notes have a whole command library: /debug, /review, /test, /doc, /refactor, a web API set, even a data science set with /model and /visualize. Writing them was fun. Most of them were never going to get used, because a command for everything is just a longer way of typing a prompt.

The docs have also moved since I wrote that note, so here's what's current, and the handful I'd keep.

Checked against the docs in September 2026.

How they work now

The idea hasn't changed. You save a prompt as a MarkdownA plain-text format where a # makes a heading and **stars** make bold. Easy to write, and easy to turn into a web page. file, and typing / plus the file name runs it. .claude/commands/review.md becomes /review. Put it in the project and commit it, and everyone who clones the repo gets it.

What's new is that the docs say custom commands have been merged into skills. A skill lives at .claude/skills/review/SKILL.md (or under ~/.claude/skills/ for your own), and it also shows up as /review. Your old command files keep working, and if a skill and a command share a name, the skill wins. For anything new, the skill folder is the recommended format.

Subfolders namespace the name. .claude/commands/frontend/component.md runs as /frontend:component.

The front matterThe block of settings at the top of a Markdown file, between two --- lines: title, date, tags and so on. in my notes was wrong, by the way. It had title: and description: lines with no --- fences around them. Here's a working one:

---
description: Review the staged changes against this repo's CLAUDE.md
argument-hint: "[what to focus on]"
---
Here are the staged changes:

!`git diff --staged`

Review them against the rules in CLAUDE.md. Pay extra attention to: $ARGUMENTS

For each problem, give the file, the line, what's wrong and the fix. If nothing's wrong, say so in one line.

Three things in there are worth knowing:

  • $ARGUMENTS is everything typed after the command name. Individual arguments are $0, $1 and so on, and they count from zero now. The first argument is $0, which catches anyone working from older notes.
  • A line starting with ! in backticks runs a shell command and drops its output into the prompt before Claude sees it. That's how the diff above gets in.
  • argument-hint shows up in the menu as a reminder of what to type.

There are more front matter fields (allowed-tools, model and friends), but description and argument hint cover most of what a small command needs.

The ones with a real job

Going through the pile in my notes, most of them are generic asks that Claude handles fine without a template. The ones worth keeping all do something a plain request doesn't:

Command Why it earns its place
/review Pulls in the diff and checks it against your CLAUDE.md, not generic best practice
/fix-bug Forces the order: expected vs actual, locate, root cause, fix, then "what test would've caught this?"
/tests Asks for happy path, edge cases and error cases separately, so the boring ones don't get skipped
/logs A fixed shape for log triage: unique errors, how often, first and last seen, likely cause

And the ones I'd let go:

  • /refactor and /doc. "Refactor this" and "document this" are already one sentence.
  • /model, /visualize and /analyze. If you're not doing that job every week, a template won't help.
  • /complete-feature, the one that plans, designs, builds, tests and documents in one shot. It's five jobs in a trench coat. I'd rather run those as separate steps and check each one.

Tip

The /fix-bug idea is the one from my notes I'd steal even if you never write a command file. The last step, "what test or guardrail would have caught this?", is where the value is. The answer usually belongs in a test, or as a line in your CLAUDE.md.

Rules of thumb

  • Wait for the third time. The first time you type a long prompt, it's a prompt. By the third, it's a command.
  • Say what shape the answer should take. "File, line, problem, fix" beats "review this."
  • Point at CLAUDE.mdA plain Markdown file of house rules that Claude Code reads at the start of every session: what the project is, how to test it, and what not to touch.More: A CLAUDE.md That Actually Helps instead of repeating it. One place for the rules, many commands that use them.
  • Keep them short. A command that needs a scroll bar is a sign it's doing too many jobs.

Where do the good prompts come from in the first place? Usually from a long conversation that finally went right. I wrote up how I turn one of those into something reusable in conversation to workflow. And for a one-off change in how Claude answers, rather than what it does, a style prompt like Execution Mode is the lighter tool.

LINKED FROM2 notes

Keep reading