Guide for building Gemini CLI TOML custom commands. Covers syntax, templates, argument handling, shell injection, and file injection...
Documentation Source: For authoritative TOML command syntax and current features, query
gemini-cli-docsskill. This skill provides navigation and examples;gemini-cli-docsprovides official Gemini CLI documentation.
This skill provides comprehensive guidance for creating Gemini CLI custom commands using TOML format. Custom commands are slash commands that extend Gemini's capabilities with project-specific or user-specific functionality.
Keywords: toml command, custom command, slash command gemini, gemini command, create command, {{args}}, @{}, !{}
Use this skill when:
~/.gemini/commands/
├── commit.toml # /commit
├── review.toml # /review
└── git/
└── log.toml # /git:log (namespaced)
.gemini/commands/
├── build.toml # /build
├── test.toml # /test
└── deploy/
└── staging.toml # /deploy:staging
# ~/.gemini/commands/hello.toml
description = "A simple greeting command"
prompt = "Say hello to the user"
description = "Generate a commit message"
prompt = """
Analyze the staged changes and generate a commit message.
Follow conventional commit format:
- feat: new features
- fix: bug fixes
- docs: documentation
- refactor: code refactoring
"""
{{args}})Arguments passed after the command are injected at {{args}}:
# /greet Kyle -> "Say hello to Kyle"
description = "Greet a person"
prompt = "Say hello to {{args}}"
If no {{args}} placeholder, arguments are appended:
description = "Analyze code"
prompt = "Analyze this code for issues"
# /analyze src/main.ts -> "Analyze this code for issues src/main.ts"
Arguments are space-separated, accessible together:
description = "Compare two files"
prompt = "Compare these files: {{args}}"
# /compare file1.ts file2.ts -> "Compare these files: file1.ts file2.ts"
!{...})Execute shell commands and inject output:
description = "Analyze git diff"
prompt = """
Review the following git diff:
~~~diff
!{git diff --staged}
~~~
Suggest improvements.
"""
Commands are confirmed before execution. Use --yolo to skip.
description = "Analyze project structure"
prompt = """
Project structure:
!{find . -type f -name "*.ts" | head -50}
Package dependencies:
!{cat package.json | jq '.dependencies'}
Analyze and suggest improvements.
"""
Combine shell injection with arguments:
description = "Grep for pattern"
prompt = """
Search results for "{{args}}":
!{grep -r "{{args}}" src/ --include="*.ts" | head -20}
Analyze these occurrences.
"""
Note: Arguments in shell blocks are automatically escaped for safety.
@{...})Inject file or directory contents:
description = "Review config"
prompt = """
Review this configuration:
@{tsconfig.json}
Suggest improvements.
"""
description = "Review setup"
prompt = """
Package config:
@{package.json}
TypeScript config:
@{tsconfig.json}
Analyze for consistency.
"""
description = "Review utilities"
prompt = """
Utility functions:
@{src/utils/}
Analyze for patterns and improvements.
"""
Note: Directory injection respects .gitignore and .geminiignore.
description = "Review file"
prompt = """
Review this file:
@{{{args}}}
Provide feedback.
"""
# /review src/main.ts -> Injects content of src/main.ts
Injection is processed in order:
@{...} - File content injection!{...} - Shell command execution{{args}} - Argument substitutionOrganize commands with directories:
~/.gemini/commands/
├── git/
│ ├── commit.toml # /git:commit
│ ├── review.toml # /git:review
│ └── log.toml # /git:log
├── test/
│ ├── unit.toml # /test:unit
│ └── e2e.toml # /test:e2e
└── deploy/
├── staging.toml # /deploy:staging
└── prod.toml # /deploy:prod
# ~/.gemini/commands/git/commit.toml
description = "Generate conventional commit message from staged changes"
prompt = """
Analyze the staged changes and generate a commit message.
## Staged Changes
~~~diff
!{git diff --staged}
~~~
## Requirements
- Use conventional commit format (feat/fix/docs/refactor/test/chore)
- Keep subject line under 72 characters
- Add body if changes are significant
- Reference issue numbers if applicable
Generate only the commit message, nothing else.
"""
# ~/.gemini/commands/review.toml
description = "Review code changes with specific focus"
prompt = """
Review the following code changes:
~~~diff
!{git diff}
~~~
Focus on: {{args}}
Provide:
1. Issues found (if any)
2. Suggestions for improvement
3. Positive observations
"""
# ~/.gemini/commands/test/generate.toml
description = "Generate tests for a file"
prompt = """
Generate comprehensive tests for this file:
@{{{args}}}
Requirements:
- Use the existing test framework (jest/vitest/pytest)
- Cover edge cases
- Include positive and negative tests
- Follow existing test patterns in the project
"""
# ~/.gemini/commands/docs/generate.toml
description = "Generate documentation for code"
prompt = """
Generate documentation for:
@{{{args}}}
Include:
- Purpose and overview
- Function/method documentation
- Usage examples
- Parameter descriptions
"""
# ~/.gemini/commands/deps/analyze.toml
description = "Analyze project dependencies"
prompt = """
Analyze these dependencies:
## package.json
@{package.json}
## Lock file (partial)
!{head -100 package-lock.json 2>/dev/null || head -100 yarn.lock 2>/dev/null || echo "No lock file"}
Identify:
1. Outdated packages
2. Security concerns
3. Unused dependencies
4. Duplicate functionality
"""
# ~/.gemini/commands/migrate.toml
description = "Help with code migration"
prompt = """
Help migrate this code: {{args}}
Current code:
@{{{args}}}
Migration requirements:
- Preserve functionality
- Follow modern patterns
- Add TypeScript types if missing
- Update deprecated APIs
"""
# Validate TOML syntax
python -c "import tomllib; tomllib.load(open('command.toml', 'rb'))"
description (string): Shown in command listprompt (string): The prompt template| Error | Cause | Fix |
|---|---|---|
| Parse error | Invalid TOML syntax | Check quotes, brackets |
| Command not found | Wrong location | Verify path |
| Args not injected | Missing {{args}} |
Add placeholder |
| Shell fails | Command error | Test command manually |
# Good
description = "Generate commit message from staged changes using conventional format"
# Bad
description = "commit stuff"
prompt = """
## Task
{what to do}
## Context
{relevant information}
## Requirements
- {requirement 1}
- {requirement 2}
## Output Format
{expected format}
"""
# Good - read-only, limited output
!{git diff --staged | head -500}
# Risky - potentially destructive
!{rm -rf {{args}}} # DANGEROUS!
prompt = """
{{args}}
If no file specified, respond: "Please specify a file path after the command"
"""
commands/
├── git/ # Git operations
│ ├── commit.toml
│ └── review.toml
├── test/ # Testing
│ ├── unit.toml
│ └── e2e.toml
└── docs/ # Documentation
└── generate.toml
gemini-cli-docs - Official command documentationpolicy-engine-builder - Tool execution policies/google-ecosystem:toml-command-builder - Interactive command builder wizard| Topic | Keywords |
|---|---|
| Basic syntax | toml command, custom command, gemini command |
| Arguments | {{args}}, command arguments, argument injection |
| Shell | !{...}, shell injection, git diff command |
| Files | @{...}, file injection, directory contents |
| Namespacing | command namespace, git:commit, organize commands |
Query: "How do I create a custom TOML command in Gemini CLI?" Expected Behavior:
Query: "How do I include git diff in a Gemini command?" Expected Behavior:
!{git diff} syntax
Success Criteria: User receives shell injection pattern with safety notesQuery: "How do I inject file contents into a Gemini command?" Expected Behavior:
@{filename} syntax
Success Criteria: User receives file injection pattern with directory supportWhen invoked directly by the user, this skill runs an interactive wizard for building Gemini CLI TOML custom commands.
--scope (user/project), and --template (git/test/docs/review/analyze). If no name provided, prompt for one.~/.gemini/commands/) or project scope (.gemini/commands/).--template specified, load pre-built template (git, test, docs, review, analyze). Otherwise start from scratch.{{args}} for arguments, @{file} for file injection, !{command} for shell injection.