Writing Your Own Commands: Save Recurring Prompts

A custom slash command is a saved markdown file: write it once, and /your-command replaces the long prompt from then on.

The core idea

If you keep typing the same prompt — "summarize my changes", "check this file" — you can save it as a custom command. Claude Code supports two formats: a markdown file under .claude/commands/ or a skill folder under .claude/skills/. Both create the same slash command: deploy.md and deploy/SKILL.md both become /deploy. Custom commands have officially been merged into skills; old command files keep working.

File structure

The file optionally starts with YAML frontmatter between two --- lines. The most important field is description: Claude uses it to recognize when the command fits the task, and can even load it automatically. After the frontmatter comes the actual prompt text.

Arguments

The $ARGUMENTS placeholder picks up everything you type after the command: with /fix-issue 123, $ARGUMENTS becomes 123. You can access individual arguments zero-based via $0, $1, and so on.

Custom command or CLAUDE.md rule?

The rule of thumb from the docs: rules that should always apply ("never push to main") belong in CLAUDE.md — it is loaded in full at every session. Procedures you only need sometimes belong in a command or skill: their text only loads when invoked and costs almost no context before that. When a CLAUDE.md section has grown into a whole procedure, that is, per the docs, exactly the moment to turn it into a command.

EXAMPLE

File `.claude/skills/fix-issue/SKILL.md`: --- description: Fixes a GitHub issue by number disable-model-invocation: true --- Fix GitHub issue $ARGUMENTS: read the issue, implement the fix, write tests. Then invoke: `/fix-issue 123`

🛠️ EXERCISE — TRY IT YOURSELF

Build your first custom command and test both ways of invoking it.

Create the file .claude/skills/summarize/SKILL.md — with a description ('Summarizes uncommitted changes') and the prompt 'Summarize the current git diff in 3 bullet points.'
Start Claude Code, change a file, and invoke /summarize directly.
Then ask in plain language 'What did I change?' and watch whether Claude loads the skill on its own.

✅ SELF-CHECK

☐ Do you know why the description field is critical for automatic loading?
☐ Can you explain when the same text would have belonged in CLAUDE.md instead?
☐ Did you understand how you would pick up arguments with $ARGUMENTS?

QUICK QUIZ

Technically, what happens when you invoke a custom command like `/fix-issue 123`?