~/.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
"""

# /greet Kyle -> "Say hello to Kyle"
description = "Greet a person"
prompt = "Say hello to {{args}}"

description = "Analyze code"
prompt = "Analyze this code for issues"
# /analyze src/main.ts -> "Analyze this code for issues src/main.ts"

description = "Compare two files"
prompt = "Compare these files: {{args}}"
# /compare file1.ts file2.ts -> "Compare these files: file1.ts file2.ts"

description = "Analyze git diff"
prompt = """
Review the following git diff:

~~~diff
!{git diff --staged}
~~~

Suggest improvements.
"""

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.
"""

description = "Grep for pattern"
prompt = """
Search results for "{{args}}":

!{grep -r "{{args}}" src/ --include="*.ts" | head -20}

Analyze these occurrences.
"""

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.
"""

description = "Review file"
prompt = """
Review this file:
@{{{args}}}

Provide feedback.
"""
# /review src/main.ts -> Injects content of src/main.ts

~/.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'))"

# 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