Custom Slash Commands

Custom commands live in ~/.claude/commands/ and are invoked with /command-name in any session. These two commands handle the most repetitive parts of the workflow: committing code and handing off context.

/commit

File: ~/.claude/commands/commit.md

Type /commit and Claude reviews your changes, picks the right commit type, writes a conventional commit message, and commits. No more writing commit messages by hand.

The Full Command File

---
description: Create a well-formatted git commit with conventional commit style
allowed-tools: Bash(git:*)
---

# Smart Git Commit

Create a well-structured git commit following conventional commit format.

## Current State

Status: !`git status --short`
Branch: !`git branch --show-current`
Staged changes: !`git diff --cached --stat`
Unstaged changes: !`git diff --stat`

## Instructions

1. **Review the changes** - Look at both staged and unstaged changes
2. **Stage if needed** - If nothing is staged but there are unstaged changes,
   ask if I should stage them (or specific files)
3. **Determine commit type** based on the changes:
   - `feat`: New feature
   - `fix`: Bug fix
   - `docs`: Documentation only
   - `style`: Formatting, no code change
   - `refactor`: Code restructuring, no behavior change
   - `test`: Adding/updating tests
   - `chore`: Maintenance, dependencies, config

4. **Write the commit message** using this format:
   type(scope): short description

   - Bullet points explaining what changed
   - Focus on WHY, not just WHAT

   Co-Authored-By: Claude <noreply@anthropic.com>

5. **Create the commit** using a heredoc
6. **Show the result** - Run `git log -1` to confirm

## Rules

- Keep the first line under 72 characters
- Use imperative mood ("add" not "added")
- Be specific about what changed
- DO NOT push unless explicitly asked
- If there are no changes to commit, say so

$ARGUMENTS

How It Works

The ! backtick syntax is a dynamic command - it runs the shell command and injects the output into the prompt before Claude sees it. So when you type /commit, Claude already knows your current branch, what's staged, and what's changed.

The $ARGUMENTS variable at the end lets you pass extra context: /commit just the CSS changes or /commit skip the test files.

allowed-tools: Bash(git:*) restricts this command to only run git commands. It can't modify files, run npm, or do anything else. This is the principle of least privilege for slash commands.

Usage

/commit                         # Commit everything
/commit only the api changes    # Selective commit
/commit fix the typo            # With context hint

/handoff

File: ~/.claude/commands/handoff.md

This is the most important command for long sessions. When your context is getting full (watch the status line - stay under 60%), run /handoff to create a summary document, then /clear to start fresh.

The Full Command File

---
description: Create a handoff document for context transfer
allowed-tools: Read, Glob, Grep, Bash(git:*), Bash(mkdir:*)
---

# Handoff Document Generation

You are creating a handoff document to transfer context to another agent
or a fresh session. This is critical for maintaining continuity when
context windows fill up or when passing work to a teammate.

## Current Git State

Branch: !`git branch --show-current 2>/dev/null || echo "not a git repo"`
Status: !`git status --short 2>/dev/null`
Recent commits: !`git log --oneline -5 2>/dev/null`

## Your Task

Generate a comprehensive handoff document by analyzing the current
session and codebase state.

**First**, ensure the context directory exists by running: `mkdir -p context`

**Then**, write the output to `context/HANDOFF.md`.

### Document Structure

Create the handoff document with these sections:

- **Session Summary** - 2-3 sentence overview
- **Completed Work** - Each task with file paths modified
- **In Progress** - Current task, state, blockers, next step
- **Remaining Tasks** - Checkbox list
- **Key Decisions Made** - Architectural choices and why
- **Important Context** - Gotchas, edge cases, warnings
- **Files Modified This Session** - List with 1-line descriptions
- **Resume Command** - What to tell the next session
- **Compact Message** - Single paragraph for /compact

### Instructions

1. Review the conversation history, todo lists, and recent git changes
2. Be specific - include exact file paths, function names, line numbers
3. Be actionable - the next agent should immediately continue work
4. Create directory with `mkdir -p context` before writing
5. Write to `context/HANDOFF.md`

$ARGUMENTS

The Handoff Workflow

This is the workflow for managing context across sessions:

  1. While working, keep an eye on context usage (status line shows percentage)
  2. At ~60% context, run /handoff
  3. Review the generated context/HANDOFF.md - make sure it captured everything
  4. Run /clear to start a fresh session
  5. In the new session, say: Read context/HANDOFF.md and continue where the previous session left off

Claude picks up exactly where it left off. The handoff doc gives it all the context it needs without carrying the full conversation history.

Add context/ to your .gitignore - handoff docs are ephemeral working documents, not part of your codebase.

Why 60%?

As context fills up, Claude's ability to recall earlier parts of the conversation degrades. This is sometimes called "context rot." By handing off at 60%, you ensure the handoff document itself is high quality (Claude still has good recall of the session), and the new session starts with a clean, focused context.

Creating Your Own Commands

Commands are just markdown files in ~/.claude/commands/. The structure:

---
description: What shows up in the command list
allowed-tools: Comma-separated list of tools this command can use
---

Your prompt content here.

Use !`shell command` for dynamic content.
Use $ARGUMENTS to capture anything typed after the command name.

Tool Restriction Patterns

Bash(git:*)          # Only git commands
Bash(npm:*)          # Only npm commands
Bash(git:*), Read    # Git commands + file reading
Read, Glob, Grep     # Read-only exploration
*                    # Everything (or omit allowed-tools)

/changelog

File: ~/.claude/commands/changelog.md

Appends an entry to docs/changelog.md using the standard Added/Changed/Fixed/Removed format. Reads recent git activity to figure out what changed, then writes concise bullet points.

Usage

/changelog                              # Infer from git + session
/changelog added search with filters    # With a hint
/changelog fixed the dark mode toggle   # Specific entry

It checks if today's date already has a section and appends to it rather than creating a duplicate. Creates docs/changelog.md if it doesn't exist.

/progress

File: ~/.claude/commands/progress.md

Creates a new file in docs/progress/ with the naming convention {date}_{time}--{slug}.md. Auto-detects the type (Build Log, Decision, Research, Code Review) and writes a structured summary of the session.

Usage

/progress                                   # Infer topic from session
/progress search implementation             # Specify the topic
/progress chose convex over supabase        # Decision log
/progress code review of auth refactor      # Review notes

Each file is self-contained - a teammate can read it with no prior context. The date prefix keeps them sorted chronologically in the folder.

Example Output

Running /progress search implementation creates:

docs/progress/2026-02-03_1400--search-implementation.md

With sections for Context, What Changed, Files Modified, and Key Takeaways.

The Full Set

With all four commands installed, the workflow becomes:

# Build something...
/commit                # Commit the work
/changelog             # Update the changelog
/progress              # Write the session log

# Context getting full...
/handoff               # Save state for next session

Creating Your Own Commands

Ideas for More

  • /deploy - Run your deployment pipeline
  • /review - Code review the current diff
  • /test - Run tests and analyze failures
  • /scaffold - Create a new component/page from a template