ailiteracynepal 🇳🇵
Text size

Chapter 02 · Section III · 10 min read

2.3 Slash commands: .claude/commands/ and $ARGUMENTS

Slash commands are the smallest customization surface — a repeated prompt captured as a file. Learn the on-disk shape, how arguments work, and where they live.

If a prompt is worth typing twice, it is worth turning into a slash command. .claude/commands/ is where they live; a plain Markdown file becomes a /name you (and your team, if committed) can invoke from any session.

The file shape

A slash command is a Markdown file at <repo>/.claude/commands/<name>.md (project-local) or ~/.claude/commands/<name>.md (user-global). The file body is the prompt Claude runs when you invoke it.

Minimal example — a /pr-desc command:

---
description: Draft a short PR description from the current branch's changes.
argument-hint: (optional) base branch, defaults to `main`
---

Diff the current branch against the base branch ($ARGUMENTS if provided,
otherwise `main`). Produce a description with three sections:

## Summary
One paragraph on the "why".

## Changes
Bullet list of significant edits. Group related ones.

## Test plan
- [ ] Manual step
- [ ] Automated: `<command>`

Under 200 words. No co-author trailers.

Save that file, restart the session or run /help, and /pr-desc is available.

Arguments

$ARGUMENTS in the file body is replaced with whatever you passed after the command name.

/pr-desc origin/develop

…substitutes origin/develop for $ARGUMENTS. If nothing was passed, $ARGUMENTS is empty — your command should handle both cases explicitly.

The argument-hint frontmatter is a human-readable one-liner shown in /help. It has no effect on behaviour; it just documents the command.

Organizing commands

Directory layout beyond one command:

.claude/
└── commands/
    ├── pr-desc.md
    ├── changelog.md
    ├── review/
    │   ├── security.md   → /review:security
    │   └── perf.md       → /review:perf
    └── ops/
        └── deploy.md     → /ops:deploy

Nested directories become namespace:name invocations. Handy for large teams where flat namespaces get noisy.

Project vs user

  • Project (<repo>/.claude/commands/) — committed. Every teammate on this repo has the command.
  • User (~/.claude/commands/) — personal. Available in every project, only for you.

Project settings shadow user settings if names collide.

Check your understanding

Quick check

—

You have three teammates who all draft PR descriptions in slightly different ways. What is the right primitive to codify one shared shape?