Custom Slash Commands

You type /review 142 into Gemini CLI. It pulls the GitHub pull request, reads the diff, checks the commit history for conventions, writes a review, and posts it as a comment. That is a custom slash command -- a reusable prompt template that encodes a multi-step workflow you run often. You define it once, in a TOML file, and invoke it with a few keystrokes. No copy-pasting the same long prompt every time. No hoping you remembered all the steps.

What you'll learn

• Custom slash commands are TOML files stored in .gemini/commands/ (project-scoped) or ~/.gemini/commands/ (user-scoped)
• Commands use for positional argument substitution and !{shell_command} for inline shell expansion
• Subdirectories create namespaced commands: .gemini/commands/git/commit.toml becomes /git:commit
• MCP Prompts from connected servers automatically become slash commands with argument support
• The description field appears in the slash command autocomplete menu, helping your team discover available commands

The problem: prompts you type over and over

Every team has workflows that follow the same shape every time. A code review follows a checklist. A release prep touches the same files and runs the same checks. A database migration means reading the schema, writing the migration, updating the models, and testing. You could type the full prompt every time. But when you type it from memory, you forget steps. When you copy it from Slack, it goes stale -- the checklist from last month does not include the new linting step someone added last week.

Custom slash commands solve this by making your reusable prompts a first-class feature of Gemini CLI. They live as files in your project repository, so they version alongside your code. When someone updates the review checklist, everyone on the team gets the update on their next git pull. And because they are invoked with /command-name, they appear in the autocomplete menu with descriptions -- discoverable without anyone having to read a wiki page.

Options and when to use each

Custom slash commands give you three ways to incorporate dynamic content. Pick the right tool for each situation.

Option	What it is good for	What it costs you	When to pick it
substitution	Passing arguments to the command at invocation time	Arguments are positional only; complex parameter structures need workarounds	The command needs one or two inputs that change each time, like an issue number or a file path
!{shell_command} expansion	Including live data from your system at command-load time	Shell command runs every time the command is invoked; slow commands make the command feel sluggish	You need the current git branch, the last five commits, today's date, or other system state baked into the prompt
MCP Prompts as slash commands	Leveraging prompts defined by an MCP server directly as commands	Requires the MCP server to be configured and connected; prompt updates need server changes	An MCP server already defines prompt templates you want available as slash commands without duplicating them in TOML

Scoping is the other decision. User-scoped commands in ~/.gemini/commands/ follow you across projects -- good for personal productivity commands like /plan or /explain. Project-scoped commands in .gemini/commands/ (relative to the project root) are available only within that project and can be checked into version control -- good for team conventions like /review or /deploy.

Build it: three commands for your project

You will create three custom slash commands: a project-scoped code review command, a user-scoped planning command, and a namespaced git command.

Command 1: /review -- a project-scoped code review

Create the directory and file:

mkdir -p .gemini/commands

Write .gemini/commands/review.toml:

description = "Reviews a pull request given its issue or PR number"

prompt = """
Please provide a detailed pull request review for GitHub issue or PR: {{args}}.

Follow these steps:
1. Use `gh pr view {{args}}` to pull the PR information
2. Use `gh pr diff {{args}}` to view the diff
3. Understand the intent of the PR using the PR description
4. If the PR description is not detailed enough to understand the intent, note it in your review
5. Check that the PR title follows Conventional Commits. Here are the last five commits to the repo as examples: !{git log --pretty=format:"%s" -n 5}
6. Search the codebase for patterns or conventions the PR should follow
7. Write a concise review of the PR, keeping in mind code quality and best practices
8. Use `gh pr comment {{args}} --body '{{review}}'` to post the review to the PR

Remember to use the GitHub CLI (`gh`) with the Shell tool for all GitHub-related tasks.
"""

The structure is minimal. Every .toml file needs at minimum a prompt key. The description is optional but recommended -- it appears in the autocomplete menu when you type / in Gemini CLI.

Breaking it down:

• captures whatever you type after /review -- so /review 142 sends 142 as the argument
• !{git log --pretty=format:"%s" -n 5} runs a shell command when the command is invoked and inlines the output. Gemini CLI sees the actual commit messages, not the shell invocation

Command 2: /plan -- a user-scoped strategist

Create the user commands directory and file:

mkdir -p ~/.gemini/commands

Write ~/.gemini/commands/plan.toml:

description = "Investigates and creates a strategic plan to accomplish a task"

prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomplish the following goal: {{args}}

You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.

Use your available read and search tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.

Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:

1. **Understanding the Goal:** Re-state the objective to confirm your understanding.
2. **Investigation and Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3. **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4. **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introducing regressions?
5. **Anticipated Challenges and Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?

Your final output should be ONLY this strategic plan.
"""

This command lives in ~/.gemini/commands/, so it is available in every project. Type /plan How do I add rate limiting to the API? from any directory and Gemini CLI switches into strategy mode.

Command 3: /git:commit -- a namespaced command

Namespaces let you group related commands. Instead of a flat list of /review, /commit, /branch (which gets unwieldy with ten or more commands), you can organize them:

mkdir -p .gemini/commands/git

Write .gemini/commands/git/commit.toml:

description = "Generate a Conventional Commits message from staged changes"

prompt = """
Generate a commit message for the currently staged changes.

First, run `git diff --staged` to see what has changed.
Then, write a commit message that follows Conventional Commits format:

<type>(<scope>): <description>

[optional body]

Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build

Rules:
- The description should be in the imperative mood ("add" not "added")
- Keep the first line under 72 characters
- If the change addresses an issue, reference it in the body

Here are the last five commit messages for style reference:
!{git log --pretty=format:"%s" -n 5}
"""

Because this file lives at .gemini/commands/git/commit.toml, the command is invoked as /git:commit. The git directory becomes the namespace. Add /git:branch, /git:pr, and /git:release and your team has an organized toolbox.

Managing commands from within Gemini CLI

Once your TOML files are in place, you can manage them without leaving the session:

/commands list      # Show all available custom commands
/commands reload    # Reload after editing a .toml file

New or modified TOML files are picked up on reload -- no restart needed.

What goes wrong

Mistake	How you notice it	The fix
TOML syntax error in the file	The command does not appear in /commands list or autocomplete	Validate the TOML with python3 -c "import tomllib; tomllib.load(open('file.toml','rb'))". Common errors: unescaped quotes inside the prompt string, missing closing triple-quotes
used but no arguments passed	Gemini CLI sends the literal string to the model instead of replacing it	Always pass at least one argument when the command uses . If the command can work without arguments, add a fallback description in the prompt
Shell expansion !{...} runs a slow command	The command takes several seconds to invoke	Cache the output in a file or environment variable and reference that instead. Or move the shell command to the first step in the prompt so Gemini CLI runs it as a tool call rather than at invocation time
User-scoped and project-scoped commands with the same name	The project-scoped command silently overrides the user-scoped one	Project commands take precedence over user commands. If you want both available, give them different names or namespaces
Command grows too large to maintain	The .toml file is 200+ lines and nobody wants to touch it	Split monolithic commands into smaller ones under a namespace. Instead of one /deploy that does everything, have /deploy:staging, /deploy:prod, /deploy:rollback

Confirm it worked

1. Create a test.toml in ~/.gemini/commands/ with prompt = "Echo back: " and description = "Test command"
2. Start Gemini CLI and type /test hello world
3. Gemini CLI should respond with something equivalent to "Echo back: hello world"
4. Run /commands list -- your test command should appear with its description
5. Delete ~/.gemini/commands/test.toml and run /commands reload -- the command should disappear

If the command does not appear, check that the file extension is .toml (not .txt or .md) and that the TOML is syntactically valid. The prompt key must be present -- it is the only required field.

Next: Extensions