Initial commit

2025-11-30 08:52:28 +08:00
commit 0b3ba5ad8e
8 changed files with 929 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "gemini",
+  "description": "Orchestrate Gemini CLI for code review, web research, and architecture analysis",
+  "version": "1.0.2",
+  "author": {
+    "name": "robbyt",
+    "email": "robbyt@robbyt.net"
+  },
+  "skills": [
+    "./skills"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# gemini
+
+Orchestrate Gemini CLI for code review, web research, and architecture analysis
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:robbyt/claude-skills:plugins/gemini",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "836ab8367703173672073b25a97ff32efdaa3c90",
+    "treeHash": "8a5ba61c99d2a51d09ca83c262538cb6d2df7ae9abe86091b1de7b5ac112ea7f",
+    "generatedAt": "2025-11-28T10:28:01.519406Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "gemini",
+    "description": "Orchestrate Gemini CLI for code review, web research, and architecture analysis",
+    "version": "1.0.2"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "b1d588418a77ff623da0485023bc818613f65dce951d204048a0d98e38ce2c20"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "7acc3389df1ef4ee577166fa16f5c7b1745ce41d6eab0f597e066380fd804481"
+      },
+      {
+        "path": "skills/cli/SKILL.md",
+        "sha256": "614bf864e8bb2d0f36cd43ef5d6f7b5786bd9c0f51aaaeaf073bece0763318d0"
+      },
+      {
+        "path": "skills/cli/references/templates.md",
+        "sha256": "caa8a2f07dcd35743a0cc315693a69124ef0c6ac627e8e5dcd80003a96f1fa4b"
+      },
+      {
+        "path": "skills/cli/references/commands.md",
+        "sha256": "04a4c5b646f5f9ce36cf86877c743a854f304b1a14812fd487bfecace6edc987"
+      },
+      {
+        "path": "skills/cli/references/patterns.md",
+        "sha256": "4490a9f835f7ed033dd20ec62160dbe15603c7775b09b1ffd8a034a6b1a43b22"
+      },
+      {
+        "path": "skills/cli/references/tools.md",
+        "sha256": "3a36f815f2efd492f19cc5239c933a2c9f642e0760cbe0af51e6234e8007f5b0"
+      }
+    ],
+    "dirSha256": "8a5ba61c99d2a51d09ca83c262538cb6d2df7ae9abe86091b1de7b5ac112ea7f"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/cli/SKILL.md
+++ b/skills/cli/SKILL.md
@@ -0,0 +1,212 @@
+---
+name: cli
+description: Orchestrate Gemini CLI (v0.17.0+) for tasks requiring current web information via Google Search, deep codebase analysis with codebase_investigator, second AI opinions on code quality/security, or parallel task processing. Trigger when user explicitly requests Gemini ("use Gemini", "ask Gemini") or when needing capabilities unique to Gemini.
+---
+
+# Gemini CLI Integration
+
+Leverage Gemini CLI for alternative AI perspectives and unique tools (Google Search, codebase_investigator).
+
+## Prerequisites
+
+⚠️ **This skill assumes Gemini CLI is already installed and authenticated.**
+
+If you haven't completed setup:
+1. See `references/commands.md` for installation and authentication instructions
+2. Complete the **manual authentication setup** (API key or OAuth)
+3. Verify with: `gemini "test" -o text`
+
+**Claude Code will NOT configure authentication for you.** This must be done manually before using this skill.
+
+## Quick Start
+
+Verify installation:
+```bash
+command -v gemini
+```
+
+Basic pattern:
+```bash
+gemini "[prompt]" -o text 2>&1
+```
+
+⏱️ **Response Time**: Gemini may take several minutes to respond, especially for complex tasks involving file analysis, web search, or codebase investigation. **Allow up to 10 minutes** for responses before assuming a timeout. The CLI will show no output while processing.
+
+Key flags:
+- `-o text`: Human-readable output
+- `-o json`: Structured output with token/tool stats
+- `-m [model]`: Model selection (e.g., `gemini-2.5-flash` for faster tasks)
+
+## Troubleshooting
+
+### Command Approval Issue
+
+**Problem**: Gemini hangs with no output when asked to execute commands.
+
+**Cause**: Gemini requires explicit user permission for any command it runs. When Claude asks Gemini to "run X command", Gemini waits for user approval and appears to hang.
+
+**Solution**: Run commands via Claude's Bash tool first, then pass the output or file paths to Gemini.
+
+**Bad Pattern** (hangs waiting for approval):
+```bash
+gemini "Run git diff --cached and review the changes" -o text
+```
+
+**Good Pattern** (runs commands first, then passes to Gemini):
+```bash
+# 1. Get the diff using Bash tool
+git diff --cached > /tmp/claude/changes.diff
+
+# 2. Pass file path to Gemini
+gemini "Review the git diff at /tmp/claude/changes.diff and provide feedback" -o text
+```
+
+**Alternative** (pass content directly):
+```bash
+# 1. Get output via Bash
+diff_output=$(git diff --cached)
+
+# 2. Save to file and reference it
+echo "$diff_output" > /tmp/claude/diff.txt
+gemini "Review /tmp/claude/diff.txt for code quality issues" -o text
+```
+
+### Sandbox Permission Error (EPERM)
+
+**Problem**: Error when running gemini commands from Claude Code:
+```
+Error: EPERM: operation not permitted, mkdir '/Users/[user]/.gemini/tmp/...'
+```
+
+**Cause**: Gemini CLI needs write access to `~/.gemini/tmp/` for chat recording. Claude Code's sandbox blocks this by default.
+
+**Solution 1** (Recommended): Use `dangerouslyDisableSandbox: true` when calling gemini via Bash tool:
+```bash
+# In Claude Code, when using Bash tool to run gemini:
+dangerouslyDisableSandbox: true
+```
+
+**Solution 2**: Add `~/.gemini/tmp` to sandbox allowlist:
+1. Run `/sandbox` command in Claude Code
+2. Add `~/.gemini/tmp` to the filesystem write allowlist
+3. Restart Claude Code
+
+**Note**: This error only affects Claude Code's sandboxed execution. Running `gemini` directly from your terminal works without these workarounds.
+
+## Working with Files
+
+**Gemini can read files directly from disk.** Tell Gemini the file path instead of embedding file content in the prompt.
+
+### Preferred Pattern (File Path)
+```bash
+gemini "Please review the bash script at path/to/file.sh for syntax errors" -o text
+```
+
+### Avoid This Pattern (Embedding Content)
+```bash
+# DON'T: Shell escaping can corrupt file content
+gemini "Review this script: $(cat path/to/file.sh)" -o text
+```
+
+**Why file paths are better:**
+- Avoids shell escaping issues (spaces in `[@]` become `[ @]`, quotes get mangled)
+- Preserves exact file content without interpretation
+- More efficient for large files
+- Clearer intent in prompts
+
+### File Operation Examples
+
+**Single file review:**
+```bash
+gemini "Review plugins/foo/test.sh for bash best practices" -o text
+```
+
+**Multi-file analysis:**
+```bash
+gemini "Compare the test patterns in plugins/python-formatter-black/tests/test.sh and plugins/go-formatter/tests/test.sh" -o text
+```
+
+**Directory analysis:**
+```bash
+gemini "Analyze all Python files in src/ directory for security issues" -o text
+```
+
+## Core Workflows
+
+### 1. Code Generation
+```bash
+gemini "Create [description] with [features]. Output complete file content." -o text
+```
+
+### 2. Code Review
+```bash
+# Provide file path - Gemini will read it directly
+gemini "Review path/to/file.js for: 1) features, 2) bugs/security issues, 3) improvements" -o text
+```
+
+### 3. Test Generation
+```bash
+gemini "Generate [Jest/pytest] tests for [file]. Focus on [areas]." -o text
+```
+
+### 4. Architecture Analysis (Unique to Gemini)
+```bash
+gemini "Use codebase_investigator to analyze this project" -o text
+```
+
+### 5. Web Research (Unique to Gemini)
+```bash
+gemini "What are the latest [topic]? Use Google Search." -o text
+```
+
+## Gemini's Unique Capabilities
+
+These tools are only available through Gemini:
+- **google_web_search**: Real-time Google Search for current info
+- **codebase_investigator**: Deep architectural analysis and dependency mapping
+- **save_memory**: Cross-session persistent memory
+
+## Rate Limits
+
+Free tier: 60 requests/min, 1000/day. CLI auto-retries with backoff. Use `-m gemini-2.5-flash` for lower-priority tasks.
+
+## Validation
+
+Always verify Gemini's output:
+- Security vulnerabilities (XSS, injection)
+- Functionality matches requirements
+- Code style consistency
+- Appropriate dependencies
+
+## JSON Output Parsing
+
+When using `-o json`, parse structured response:
+```json
+{
+  "response": "actual content",
+  "stats": {
+    "models": { "tokens": {...} },
+    "tools": { "byName": {...} }
+  }
+}
+```
+
+## Configuration
+
+Optional: Create `.gemini/GEMINI.md` in project root for persistent context Gemini auto-reads.
+
+Session management:
+```bash
+gemini --list-sessions               # List sessions
+echo "follow-up" | gemini -r 1 -o text   # Resume by index
+```
+
+## Reference Documentation
+
+For detailed guidance, see:
+- **references/commands.md**: Complete CLI flags and options reference
+- **references/patterns.md**: Advanced integration patterns (Generate-Review-Fix, background execution, model selection, validation pipelines)
+- **references/templates.md**: Reusable prompt templates for common operations
+- **references/tools.md**: Gemini's built-in tools documentation and comparison with Claude Code
+
+Load these references when you need deeper knowledge about specific aspects of Gemini CLI usage.
--- a/skills/cli/references/commands.md
+++ b/skills/cli/references/commands.md
@@ -0,0 +1,66 @@
+# Gemini CLI Quick Reference
+
+Minimal reference for using Gemini CLI with this skill. For complete documentation, see [official Gemini CLI docs](https://github.com/google-gemini/gemini-cli).
+
+## Installation
+
+**macOS (Recommended):**
+```bash
+brew install gemini-cli
+```
+
+**Cross-Platform (npm):**
+```bash
+npm install -g @google/gemini-cli
+```
+
+**Verify:**
+```bash
+gemini --version  # Should show v0.17.0+
+```
+
+## Authentication
+
+⚠️ **IMPORTANT:** Gemini CLI must be authenticated before using this skill. Claude Code will NOT configure authentication for you.
+
+**Prerequisites:**
+- Gemini CLI installed and authenticated
+- Test that `gemini "test" -o text` works
+
+**Setup instructions:** See the [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for authentication setup.
+
+**If this skill fails with auth errors:**
+- Complete authentication setup manually using official docs
+- Verify with: `gemini "test" -o text`
+- Then retry using the skill
+
+## Basic Usage
+
+**For code review:**
+```bash
+gemini "Review this code for security issues: [code]" -o text
+```
+
+**For web research:**
+```bash
+gemini "What's new in React 19? Use Google Search." -o text
+```
+
+**For architecture analysis:**
+```bash
+gemini "Use codebase_investigator to analyze this project" -o text
+```
+
+## Common Options
+
+Run `gemini --help` for complete list. Key options used by this skill:
+
+- `-o text` - Human-readable output (default for consulting)
+- `-o json` - Structured output with stats
+- `-m gemini-2.5-flash` - Faster model for simple tasks
+
+## More Information
+
+- **Full CLI reference:** `gemini --help`
+- **Official documentation:** https://github.com/google-gemini/gemini-cli
+- **Models, configuration, troubleshooting:** See official docs above
--- a/skills/cli/references/patterns.md
+++ b/skills/cli/references/patterns.md
@@ -0,0 +1,274 @@
+# Gemini CLI Integration Patterns
+
+**Core Principle:** Claude Code handles all code writing, file operations, and commands. Gemini provides consulting (second opinions) and search capabilities.
+
+---
+
+## Pattern 1: Cross-Validation (Primary Pattern)
+
+Leverage both AIs for highest quality by using their complementary strengths.
+
+### Claude Generates, Gemini Reviews
+```bash
+# 1. Claude writes code (using normal Claude Code tools)
+# (Claude generates the code directly)
+
+# 2. Get Gemini's review
+gemini "Review this code for bugs and security issues:
+[paste code Claude wrote]
+Provide specific findings with severity levels." -o text
+
+# 3. Claude implements fixes based on Gemini's feedback
+# (Claude makes the changes)
+```
+
+### Gemini Researches, Claude Implements
+```bash
+# 1. Gemini researches best practices
+gemini "Use Google Search to find current best practices for [topic]. Summarize key recommendations." -o text
+
+# 2. Claude implements based on research
+# (Claude writes the code following the recommendations)
+
+# 3. Optional: Gemini reviews implementation
+gemini "Review this implementation of [topic]. Does it follow best practices found earlier?" -o text
+```
+
+### Gemini Analyzes Architecture, Claude Refactors
+```bash
+# 1. Gemini maps the codebase
+gemini "Use codebase_investigator to analyze this project's architecture. Identify areas needing improvement." -o text
+
+# 2. Claude refactors based on analysis
+# (Claude makes the architectural changes)
+
+# 3. Gemini validates changes
+gemini "Use codebase_investigator again. Has the architecture improved?" -o text
+```
+
+### Complementary Strengths
+- **Claude:** Complex reasoning, following instructions, writing code, file operations
+- **Gemini:** Current web knowledge, Google Search access, deep codebase investigation
+
+---
+
+## Pattern 2: JSON Output for Analysis
+
+Use JSON output to programmatically process Gemini's analysis results.
+
+```bash
+gemini "Review [file] for security issues" -o json 2>&1
+```
+
+### Parsing Response
+```python
+import json
+
+result = json.loads(output)
+analysis = result["response"]
+tokens_used = result["stats"]["models"]["gemini-3-pro"]["tokens"]["total"]
+tools_used = result["stats"]["tools"]["byName"]
+```
+
+### Use Cases
+- Extract specific security findings
+- Track analysis costs (token usage)
+- Monitor tool usage (google_web_search, codebase_investigator)
+- Build automated review pipelines
+
+---
+
+## Pattern 3: Model Selection Strategy
+
+Choose the appropriate Gemini model for the consultation type.
+
+### Decision Tree
+
+```
+Is this deep architecture analysis or complex codebase review?
+├── Yes → Use default (Gemini 3 Pro)
+└── No → Is it a quick web search or simple review?
+    ├── Yes → Use gemini-2.5-flash
+    └── No → Use gemini-2.5-flash
+```
+
+### Examples
+```bash
+# Deep analysis: Use Pro (default)
+gemini "Use codebase_investigator to analyze authentication architecture" -o text
+
+# Quick search: Use Flash
+gemini "What's the latest version of React? Use Google Search." -m gemini-2.5-flash -o text
+
+# Code review: Use Flash for faster feedback
+gemini "Quick review of this function for obvious bugs" -m gemini-2.5-flash -o text
+```
+
+---
+
+## Pattern 4: Rate Limit Management
+
+Strategies for working within Gemini's free tier limits (60/min, 1000/day).
+
+### Let Auto-Retry Handle It
+Default behavior - CLI retries automatically with backoff.
+
+### Use Flash for Lower Priority
+```bash
+# Critical review: Use Pro
+gemini "Security review of authentication system" -o text
+
+# Less critical: Use Flash (separate quota)
+gemini "Quick opinion on this variable naming" -m gemini-2.5-flash -o text
+```
+
+### Batch Related Questions
+```bash
+# Instead of multiple calls:
+gemini "Review file A"
+gemini "Review file B"
+gemini "Review file C"
+
+# Single batched call:
+gemini "Review files A, B, and C. For each file, identify bugs and security issues." -o text
+```
+
+---
+
+## Pattern 5: Context Enrichment
+
+Provide rich context for better analysis.
+
+### Using File References
+```bash
+gemini "Based on @./package.json and @./src/auth.js, review the authentication implementation for security issues." -o text
+```
+
+### Using GEMINI.md
+Create `.gemini/GEMINI.md` for persistent context:
+```markdown
+# Project Context
+
+This is a Python project using:
+- Framework: FastAPI
+- Database: SQLAlchemy with PostgreSQL
+- Testing: pytest
+
+## Review Guidelines
+- Follow PEP 8 style guidelines
+- Check for type hints (PEP 484)
+- Verify async/await patterns
+```
+
+### Explicit Context in Prompt
+```bash
+gemini "Given this context:
+- Python 3.11+ with FastAPI
+- Using async/await patterns
+- Type hints required
+
+Review this module for type safety and Python best practices." -o text
+```
+
+---
+
+## Pattern 6: Session Continuity for Iterative Analysis
+
+Use sessions for multi-turn consultations.
+
+```bash
+# Initial analysis
+gemini "Use codebase_investigator to analyze this project's architecture" -o text
+# Session saved automatically
+
+# List available sessions
+gemini --list-sessions
+
+# Continue analysis in same session
+echo "What patterns did you find in the authentication flow?" | gemini -r 1 -o text
+
+# Further refinement
+echo "Are there any security concerns with that pattern?" | gemini -r 1 -o text
+```
+
+### Use Cases
+- Iterative architecture analysis
+- Multi-step security reviews
+- Building on previous research findings
+
+---
+
+## Pattern 7: Validation of Recommendations
+
+Always validate Gemini's recommendations before implementing.
+
+### Validation Steps
+
+1. **Verify Against Official Docs**
+   - Gemini's web search may find outdated information
+   - Cross-reference with official documentation
+
+2. **Test Recommendations**
+   - Don't blindly implement security suggestions
+   - Verify they work in your specific context
+
+3. **Review for Context**
+   - Gemini may miss project-specific constraints
+   - Ensure recommendations fit your architecture
+
+4. **Get Multiple Opinions**
+   - For critical changes, consult multiple sources
+   - Use Claude's reasoning to evaluate Gemini's suggestions
+
+---
+
+## Best Practices
+
+### Do: Use Gemini For
+- ✓ Code review and security audits
+- ✓ Web research for current information
+- ✓ Architecture analysis with codebase_investigator
+- ✓ Second opinions on design decisions
+- ✓ Error diagnosis and troubleshooting
+- ✓ Best practice research
+
+### Don't: Use Gemini For
+- ✗ Primary code generation (that's Claude's job)
+- ✗ File operations (use Claude's tools)
+- ✗ Running commands (use Claude's Bash tool)
+- ✗ Direct bug fixes (Claude should fix, Gemini reviews)
+- ✗ Building features (Claude builds, Gemini consults)
+
+### Remember
+- **Claude writes code, Gemini provides feedback**
+- **Claude operates files, Gemini analyzes them**
+- **Claude implements, Gemini validates**
+
+---
+
+## Anti-Patterns to Avoid
+
+### Don't: Use Gemini as Primary Code Generator
+Gemini can generate code, but that's not its role in this skill. Claude Code is better suited for following complex instructions and integrating with your workflow.
+
+**Do**: Have Claude generate code, then get Gemini's review for a second perspective.
+
+### Don't: Ignore Rate Limits
+Hammering the API wastes time on retries.
+
+**Do**: Use appropriate models and batch related questions.
+
+### Don't: Trust Recommendations Blindly
+Gemini can provide outdated or context-inappropriate suggestions.
+
+**Do**: Validate recommendations against official docs and your project context.
+
+### Don't: Over-Specify in Single Prompt
+Extremely long prompts can confuse the model.
+
+**Do**: Break complex analyses into focused questions.
+
+### Don't: Forget Project Context
+Gemini doesn't automatically know your project conventions.
+
+**Do**: Use `.gemini/GEMINI.md` or explicit context in prompts for better analysis.
--- a/skills/cli/references/templates.md
+++ b/skills/cli/references/templates.md
@@ -0,0 +1,168 @@
+# Gemini CLI Prompt Templates
+
+**Important:** Gemini provides consulting and search services. Claude Code remains responsible for all code writing, file operations, and command execution.
+
+Use these templates for:
+- **Code review** (second opinions)
+- **Web research** (current information)
+- **Architecture analysis** (codebase investigation)
+
+---
+
+## Code Review
+
+### Comprehensive Review
+```bash
+gemini "Review [file] that Claude Code wrote and tell me:
+1) What features it has
+2) Any bugs or security issues
+3) Suggestions for improvement
+4) Code quality assessment" -o text
+```
+
+### Security-Focused Review
+```bash
+gemini "Review [file] for security vulnerabilities including:
+- XSS (cross-site scripting)
+- SQL injection
+- Command injection
+- Insecure data handling
+- Authentication issues
+Report findings with severity levels." -o text
+```
+
+### Performance Review
+```bash
+gemini "Analyze [file] for performance issues:
+- Inefficient algorithms
+- Memory leaks
+- Unnecessary re-renders
+- Blocking operations
+- Optimization opportunities
+Provide specific recommendations." -o text
+```
+
+### Code Quality Assessment
+```bash
+gemini "Assess code quality of [file]:
+- Readability and maintainability
+- Adherence to best practices
+- Potential technical debt
+- Suggested improvements" -o text
+```
+
+---
+
+## Web Research
+
+### Current Information
+```bash
+gemini "What are the latest [topic] as of [date]? Use Google Search to find current information. Summarize key points." -o text
+```
+
+### Library/API Research
+```bash
+gemini "Research [library/API] and provide:
+- Latest version and changes
+- Best practices
+- Common patterns
+- Gotchas to avoid
+Use Google Search for current information." -o text
+```
+
+### Comparison Research
+```bash
+gemini "Compare [option A] vs [option B] for [use case]. Use Google Search for current benchmarks and community opinions. Provide recommendation." -o text
+```
+
+### Security Vulnerability Research
+```bash
+gemini "What are the known security vulnerabilities in [library] version [x.y.z]? Use Google Search. Include CVE numbers and severity ratings." -o text
+```
+
+### Best Practices Research
+```bash
+gemini "What are the current best practices for [topic] as of [date]? Use Google Search to find recent articles and official documentation." -o text
+```
+
+---
+
+## Architecture Analysis
+
+### Project Analysis
+```bash
+gemini "Use the codebase_investigator tool to analyze this project. Report on:
+- Overall architecture
+- Key dependencies
+- Component relationships
+- Potential issues" -o text
+```
+
+### Dependency Analysis
+```bash
+gemini "Analyze dependencies in this project:
+- Direct vs transitive
+- Outdated packages
+- Security vulnerabilities
+- Bundle size impact
+Use available tools to gather information." -o text
+```
+
+### Flow Analysis
+```bash
+gemini "Use codebase_investigator to map the [authentication/payment/data] flow in this project. Identify all components involved." -o text
+```
+
+### Technical Debt Assessment
+```bash
+gemini "Use codebase_investigator to identify potential technical debt:
+- Deprecated patterns
+- Inconsistent conventions
+- Missing documentation
+- Complex dependencies" -o text
+```
+
+---
+
+## Code Explanation
+
+### Detailed Explanation
+```bash
+gemini "Explain what [file/function] does in detail:
+- Purpose and use case
+- How it works step by step
+- Key algorithms/patterns used
+- Dependencies and side effects" -o text
+```
+
+### Error Diagnosis
+```bash
+gemini "Diagnose this error:
+[error message]
+Context: [relevant context]
+Provide:
+- Root cause
+- Recommended solution approach
+- Prevention tips" -o text
+```
+
+### Design Pattern Identification
+```bash
+gemini "Analyze [file/codebase] and identify the design patterns being used. Explain their purpose and effectiveness." -o text
+```
+
+---
+
+## Template Variables
+
+Use these placeholders in templates:
+
+- `[file]` - File path or name
+- `[directory]` - Directory path
+- `[library/API]` - Library or API name
+- `[topic]` - Subject matter for research
+- `[date]` - Date for time-sensitive queries
+- `[use case]` - Specific use case scenario
+- `[option A/B]` - Options to compare
+- `[error message]` - Error text
+- `[context]` - Relevant contextual information
--- a/skills/cli/references/tools.md
+++ b/skills/cli/references/tools.md
@@ -0,0 +1,133 @@
+# Gemini CLI Built-in Tools
+
+Gemini's unique capabilities and tool comparison with Claude Code.
+
+## Unique Tools (Gemini Only)
+
+### google_web_search
+
+Real-time internet search via Google Search API.
+
+**Usage:**
+```bash
+gemini "What are the latest React 19 features? Use Google Search." -o text
+```
+
+**Best For:**
+- Current events and news
+- Latest library versions/documentation
+- Community opinions and benchmarks
+- Anything requiring post-cutoff information
+
+**Examples:**
+- "What are the security vulnerabilities in lodash 4.x? Use Google Search."
+- "Best practices for Next.js 14 app router in November 2025."
+
+---
+
+### codebase_investigator
+
+Deep architectural analysis and dependency mapping.
+
+**Usage:**
+```bash
+gemini "Use codebase_investigator to analyze this project" -o text
+```
+
+**Output Includes:**
+- Architecture overview
+- Component relationships
+- Dependency chains
+- Potential issues/inconsistencies
+
+**Best For:**
+- Onboarding to unfamiliar codebases
+- Understanding legacy systems
+- Finding hidden dependencies
+- Architecture documentation
+
+**Example:**
+```bash
+gemini "Use codebase_investigator to map the authentication flow" -o text
+```
+
+---
+
+### save_memory
+
+Cross-session persistent memory storage.
+
+**Usage:**
+```bash
+gemini "Remember that this project uses Zustand for state management. Save this to memory." -o text
+```
+
+**Best For:**
+- Project conventions
+- User preferences
+- Recurring context
+- Custom instructions
+
+---
+
+## Tool Comparison
+
+Gemini has standard file/search tools similar to Claude Code, plus unique capabilities:
+
+| Capability | Claude Code | Gemini CLI |
+|------------|-------------|------------|
+| File listing | LS, Glob | list_directory, glob |
+| File reading | Read | read_file |
+| Code search | Grep | search_file_content |
+| Web fetch | WebFetch | web_fetch |
+| **Web search** | WebSearch | **google_web_search** ⭐ |
+| **Architecture** | Task (Explore) | **codebase_investigator** ⭐ |
+| **Memory** | N/A | **save_memory** ⭐ |
+| Task tracking | TodoWrite | write_todos |
+
+⭐ = Gemini's unique advantages
+
+---
+
+## JSON Output Stats
+
+When using `-o json`, tool usage is reported in stats:
+
+```json
+{
+  "response": "actual content",
+  "stats": {
+    "tools": {
+      "totalCalls": 3,
+      "byName": {
+        "google_web_search": {
+          "count": 1,
+          "success": 1,
+          "durationMs": 3000
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool Combination Patterns
+
+Leverage multiple tools in single prompts:
+
+**Research → Implement:**
+```bash
+gemini "Use Google Search to find best practices for [topic], then implement them" -o text
+```
+
+**Analyze → Report:**
+```bash
+gemini "Use codebase_investigator to analyze the project, then write a summary report" -o text
+```
+
+**Search → Suggest:**
+```bash
+gemini "Find all files using deprecated API, read them, and suggest updates" -o text
+```