Gemini CLI Skill Guide
PATH Setup (CRITICAL)
Subagents run with a minimal PATH. Always include mise/node paths:
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && gemini <args>
Baseline Rules
Always apply these for programmatic (headless) execution:
-p "<prompt>"— required for headless mode--yolo— required when creating or editing files (auto-approves actions)--output-format json— recommended for programmatic processing
Command Templates
New Task (read-only)
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && NODE_OPTIONS="--no-warnings" gemini -p "<prompt>"
New Task (with file edits)
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && NODE_OPTIONS="--no-warnings" gemini -p "<prompt>" --yolo
New Task (with additional directories)
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && NODE_OPTIONS="--no-warnings" gemini -p "<prompt>" --yolo --include-directories src,lib
Pipe file content
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && cat <file> | NODE_OPTIONS="--no-warnings" gemini -p "<prompt describing what to do with the content>"
Resume Session
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && NODE_OPTIONS="--no-warnings" gemini --resume latest -p "<prompt>"
Note: Use --resume latest for most recent session, or --resume <id> for a specific session. Use --list-sessions to see available sessions.
JSON output for parsing
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && NODE_OPTIONS="--no-warnings" gemini -p "<prompt>" --output-format json | jq -r '.response'
Approval Modes
| Task Type | Flags | Notes |
|---|---|---|
| Analysis, review, Q&A | (none) | Read-only by default |
| Create or edit files | --yolo |
Auto-approves all actions |
| Controlled edits | --approval-mode auto_edit |
Auto-approve edits only |
Model Selection
When the calling agent specifies requirements, translate to flags:
| Requirement | Flag | Notes |
|---|---|---|
| Default / high-quality | -m gemini-3-pro |
Best for complex reasoning |
| Fast / cheap | -m gemini-3-flash |
Quick, straightforward tasks |
If not specified, use default model (no flag needed).
Output Formats
| Format | Flag | Use Case |
|---|---|---|
| Text (default) | (none) | Human-readable output |
| JSON | --output-format json |
Programmatic processing, includes stats |
| Streaming JSON | --output-format stream-json |
Real-time monitoring, live UI |
JSON Response Structure
{
"response": "The AI-generated content",
"stats": { "models": {...}, "tools": {...}, "files": {...} },
"error": { "type": "...", "message": "..." } // only if error occurred
}
File References
Pipe file content to Gemini:
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && cat src/config.ts | gemini -p "Explain this configuration"
Or use --include-directories to give Gemini access:
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH" && gemini -p "Analyze the authentication module" --include-directories src/auth
Interpreting Results
Success indicators
- JSON output has
responsefield with content - No
errorfield in JSON output stats.files.totalLinesAdded> 0 for edit tasks
Failure indicators
- Non-zero exit code
- JSON output contains
errorfield error.typeindicates failure category (ApiError, AuthError, etc.)
Scope creep indicators
- Mentions of "I also..." or "While I was at it..."
stats.filesshows changes to unexpected files- Response describes work beyond the original request
Redirection indicators
- Output describes different work than requested
- "Instead of X, I did Y..."
- Solving a different problem than specified
After Completion
Report to user: "You can resume this Gemini session by saying 'gemini resume'."
Session Management
--list-sessions— Show all recorded sessions--resume latest— Resume most recent session--resume <id>— Resume specific session by ID--delete-session <id>— Remove a session
Error Handling
- If command exits non-zero: stop and report the error
- If JSON contains
errorfield: reporterror.typeanderror.message - If output contains warnings: summarize and ask how to proceed
- Before
--yolo: confirm with user unless pre-authorized
Reference
Useful Patterns
# Set PATH for all commands
export PATH="$HOME/.local/share/mise/installs/node/24.13.0/bin:$HOME/.local/bin:$PATH"
# Code review
cat src/auth.py | gemini -p "Review for security issues"
# Generate commit message
git diff --cached | gemini -p "Write a concise commit message"
# Batch analysis
for file in src/*.py; do
cat "$file" | gemini -p "Find bugs" --output-format json | jq -r '.response'
done
Debug Mode
Add --debug or -d for verbose output when troubleshooting.