Command Authoring Deep Dive

Custom slash commands in Gemini CLI are .toml files that live in .gemini/commands/ (project scope) or ~/.gemini/commands/ (user scope). Each file defines a command name, description, and prompt template. When you type /commandname, Gemini loads the .toml, interpolates {{args}} with whatever you typed after the command name, and executes the resulting prompt. This is how you encode team workflows — code reviews, changelog generation, test scaffolding, deployment checklists — into repeatable, shareable commands.

The .toml format is intentionally simple. A [command] table with three keys: name, description, and prompt. The prompt field supports multi-line strings, {{args}} interpolation, and shell execution via !{...} syntax. Shell execution is powerful — !{git diff --cached} injects the actual staged diff into your prompt at runtime. This means your commands can incorporate live project state, not just static templates.

[command]
name = "test-plan"
description = "Generate a test plan for changed files"
prompt = """
Here are the files that changed:
!{git diff --name-only HEAD~1}

Here is the actual diff:
!{git diff HEAD~1}

Generate a comprehensive test plan:
1. Unit tests needed for new/changed functions
2. Integration tests for affected workflows
3. Edge cases to cover
4. Regression risks to validate

Format as a markdown checklist I can paste into a PR description.
"""

1. Create the .toml file Place it in .gemini/commands/ for project scope (shared with team via git) or ~/.gemini/commands/ for personal scope. Name it descriptively: deploy-check.toml, review-security.toml.
2. Define the command table Set name (supports namespacing with colons like "git:commit"), description (shown in /help), and prompt (the template Gemini executes).
3. Add dynamic elements Use {{args}} for user input and !{...} for shell command output. Test with simple prompts first, then add complexity.
4. Test and iterate Run the command with sample inputs. Refine the prompt based on output quality. Check in the final version so your team benefits.