@biggora/claude-plugins 1.0.0 → 1.1.0

package/src/skills/gemini-cli/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: gemini-cli
+description: >
+  Use this skill whenever the user wants to install, configure, or use the Gemini CLI
+  (gemini-cli) tool. Trigger this skill for tasks such as: installing gemini-cli via npm/npx/brew,
+  setting up authentication (API key, Google OAuth, Vertex AI), running non-interactive/headless
+  prompts with -p flag, configuring settings.json, creating GEMINI.md context files, writing
+  custom slash commands (.toml files), connecting MCP servers, creating extensions, automating
+  tasks with shell scripts, using --output-format json/stream-json, managing chat sessions,
+  using /memory commands, --yolo mode, or any scripting/automation involving gemini-cli.
+  Also trigger when user asks about integrating Gemini models into CLI workflows, CI/CD pipelines,
+  or programmatic use of the Gemini API through the CLI tool.
+---
+
+# Gemini CLI Skill
+
+Gemini CLI is an open-source AI agent that brings Gemini models directly into the terminal.
+It supports interactive REPL sessions, headless/non-interactive scripting, MCP servers, custom
+slash commands, and extension-based workflows.
+
+**Reference files** (read when needed):
+- `references/commands.md` — slash commands, built-in commands reference
+- `references/configuration.md` — settings.json, GEMINI.md, environment variables
+- `references/mcp-and-extensions.md` — MCP server setup, extensions authoring
+- `references/headless-and-scripting.md` — non-interactive mode, automation, CI/CD patterns
+
+---
+
+## Installation
+
+```bash
+# Instant use, no install
+npx @google/gemini-cli
+
+# Global install (recommended)
+npm install -g @google/gemini-cli
+
+# macOS/Linux via Homebrew
+brew install gemini-cli
+
+# Specific channels
+npm install -g @google/gemini-cli@latest    # stable (weekly Tuesdays)
+npm install -g @google/gemini-cli@preview   # preview (weekly, less vetted)
+npm install -g @google/gemini-cli@nightly   # nightly (daily builds)
+```
+
+---
+
+## Authentication
+
+Choose one method:
+
+### Option 1: Google OAuth (recommended for individuals)
+```bash
+gemini   # → choose "Login with Google" → browser flow
+```
+- Free: 60 req/min, 1,000 req/day
+- No API key needed
+
+### Option 2: Gemini API Key
+```bash
+export GEMINI_API_KEY="your_key_here"
+# Get key: https://aistudio.google.com/apikey
+gemini
+```
+- Free: 1,000 req/day (Gemini Flash/Pro mix)
+- Can also store in `~/.gemini/.env` or `./.gemini/.env`
+
+### Option 3: Vertex AI (enterprise)
+```bash
+export GOOGLE_API_KEY="your_key"
+export GOOGLE_GENAI_USE_VERTEXAI=true
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+gemini
+```
+
+---
+
+## Basic Usage
+
+```bash
+# Start interactive session in current directory
+gemini
+
+# Include extra directories as context
+gemini --include-directories ../lib,../docs
+
+# Use a specific model
+gemini -m gemini-2.5-flash
+gemini -m gemini-2.5-pro
+
+# Non-interactive: single prompt, then exit
+gemini -p "Explain the architecture of this codebase"
+
+# Reference files in prompt with @ syntax
+gemini -p "Review @./src/auth.py for security issues"
+
+# Pipe stdin
+cat error.log | gemini -p "What went wrong here?"
+git diff --cached | gemini -p "Write a concise commit message"
+```
+
+---
+
+## Headless / Non-Interactive Mode
+
+Headless mode is triggered by `-p` flag or non-TTY environment.
+
+```bash
+# Plain text output (default)
+gemini -p "Explain Docker" > output.txt
+
+# Structured JSON output (recommended for scripting)
+gemini -p "Explain Docker" --output-format json
+
+# Streaming JSONL (for long-running tasks)
+gemini -p "Run tests and analyze results" --output-format stream-json
+
+# Extract response field with jq
+gemini -p "List top 5 Python testing frameworks" --output-format json | jq -r '.response'
+
+# Auto-accept all tool actions (YOLO mode) — use with care in automation
+gemini -p "Generate unit tests for @./src/utils.js" --yolo
+```
+
+### JSON output schema
+```json
+{
+  "response": "...",
+  "stats": {
+    "models": { "gemini-2.5-pro": { "tokens": {...}, "api": {...} } },
+    "tools": { "totalCalls": 1, "totalSuccess": 1 },
+    "files": { "totalLinesAdded": 0, "totalLinesRemoved": 0 }
+  }
+}
+```
+
+For full scripting patterns → read `references/headless-and-scripting.md`
+
+---
+
+## Interactive Session: Key Commands
+
+| Command | Description |
+|---|---|
+| `/help` | List all commands |
+| `/tools` | Show available tools |
+| `/mcp list` | List MCP servers and their status |
+| `/mcp status` | Detailed MCP connection info |
+| `/chat save <name>` | Save current session |
+| `/chat resume <name>` | Resume a saved session |
+| `/memory add <text>` | Add persistent fact to GEMINI.md memory |
+| `/memory show` | Show current memory contents |
+| `/restore` | List checkpoints |
+| `/restore <file>` | Restore a checkpoint |
+| `/bug` | Report an issue directly from CLI |
+| `Ctrl+Y` | Toggle YOLO mode (auto-accept all tools) |
+
+---
+
+## GEMINI.md — Project Context Files
+
+Create `GEMINI.md` at project root (or `~/.gemini/GEMINI.md` for global context):
+
+```markdown
+# My Project
+
+## Guidelines
+- All Python code must follow PEP 8
+- Use 2-space indentation for JavaScript
+
+## Architecture
+@./docs/architecture.md
+
+## Style Guides
+@./src/frontend/react-style-guide.md
+```
+
+**Hierarchy** (all are loaded and merged):
+1. `~/.gemini/GEMINI.md` — global user context
+2. `<project>/.gemini/GEMINI.md` — project context
+3. Sub-directory `GEMINI.md` files — scoped context
+
+---
+
+## Custom Slash Commands (.toml)
+
+Create `.toml` files to define reusable commands:
+
+**Locations:**
+- `~/.gemini/commands/<name>.toml` → user-scoped `/name`
+- `<project>/.gemini/commands/<name>.toml` → project-scoped `/name`
+- `<project>/.gemini/commands/git/commit.toml` → namespaced `/git:commit`
+
+**Minimal example** (`~/.gemini/commands/plan.toml`):
+```toml
+prompt = "Only plan the changes step-by-step. Do NOT start implementation yet."
+```
+
+**Full example** (`~/.gemini/commands/review.toml`):
+```toml
+description = "Code review with focus on security and performance"
+prompt = """
+Review the following code for:
+1. Security vulnerabilities
+2. Performance issues
+3. Code style
+
+Code to review: {{args}}
+"""
+```
+
+**With shell execution:**
+```toml
+description = "Review staged git changes"
+prompt = "Review these git changes for issues:\n!{git diff --cached}"
+```
+
+For MCP prompts as slash commands → read `references/mcp-and-extensions.md`
+
+---
+
+## settings.json Configuration
+
+Location: `~/.gemini/settings.json` (global) or `<project>/.gemini/settings.json`
+
+```json
+{
+  "model": "gemini-2.5-pro",
+  "theme": "dark",
+  "autoAccept": false,
+  "coreTools": ["read_file", "write_file", "run_shell_command"],
+  "excludeTools": ["dangerous_tool"],
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "$GITHUB_TOKEN"
+      }
+    }
+  }
+}
+```
+
+For full configuration reference → read `references/configuration.md`
+
+---
+
+## MCP Server Integration
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "myServer": {
+      "command": "node",
+      "args": ["./mcp-server.js"],
+      "env": { "API_KEY": "$MY_API_KEY" },
+      "timeout": 15000,
+      "trust": false
+    }
+  }
+}
+```
+
+**CLI management commands:**
+```bash
+gemini mcp add <name>     # add server
+gemini mcp list           # list configured servers
+gemini mcp remove <name>  # remove server
+```
+
+**Invoke tools in prompts:**
+```
+> @github List my open pull requests
+> @database Find inactive users from last 30 days
+```
+
+For detailed MCP setup and extensions → read `references/mcp-and-extensions.md`
+
+---
+
+## Extensions
+
+Extensions bundle MCP servers + GEMINI.md + custom commands into a reusable package.
+
+**Install from URL:**
+```bash
+gemini extension install https://github.com/GoogleCloudPlatform/cloud-run-mcp
+```
+
+**Browse gallery:** https://geminicli.com/extensions/
+
+**Extension structure:**
+```
+my-extension/
+├── gemini-extension.json    # manifest
+└── GEMINI.md                # context (optional)
+```
+
+```json
+// gemini-extension.json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": { "command": "node my-server.js" }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+---
+
+## Common Patterns
+
+### Commit message automation
+```bash
+result=$(git diff --cached | gemini -p "Write a concise commit message" --output-format json)
+echo "$result" | jq -r '.response' | git commit -F -
+```
+
+### Batch file processing
+```bash
+for file in src/**/*.py; do
+  gemini -p "Generate docstrings for @$file" --output-format json | jq -r '.response' > "${file%.py}_docs.md"
+done
+```
+
+### Security code review
+```bash
+cat src/auth.py | gemini -p "Review for security vulnerabilities" > security-review.txt
+```
+
+### Generate OpenAPI spec
+```bash
+result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec" --output-format json)
+echo "$result" | jq -r '.response' > openapi.json
+```
+
+### CI/CD pipeline integration
+```bash
+# In GitHub Actions / CI script
+export GEMINI_API_KEY="${{ secrets.GEMINI_API_KEY }}"
+gemini -p "Analyze test failures in @./test-results.xml and suggest fixes" \
+  --output-format json \
+  --yolo \
+  | jq -r '.response'
+```
+
+---
+
+## Model Selection
+
+```bash
+gemini -m gemini-2.5-pro    # most powerful, 1M context
+gemini -m gemini-2.5-flash  # fast, efficient (default routing)
+```
+
+Models available through Gemini API: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`, etc.
+For Vertex AI: additional enterprise models available.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `command not found: gemini` | Run `npm install -g @google/gemini-cli` or use `npx` |
+| Auth errors | Check `GEMINI_API_KEY` env var or re-run `gemini` and re-authenticate |
+| Rate limit errors | Free tier: 60 req/min, 1000/day — wait or upgrade |
+| MCP server not connecting | Check `/mcp status`, verify server binary is installed |
+| Slash command not recognized in headless | Known limitation — embed prompt text directly for now |
+| Tool confirmation loops | Add `--yolo` flag for automation, or set `"autoAccept": true` in settings.json |
+
+Full troubleshooting: https://geminicli.com/docs/resources/troubleshooting/

package/src/skills/gemini-cli/references/commands.md

@@ -0,0 +1,145 @@
+# Commands Reference
+
+## CLI Flags (startup)
+
+```
+gemini [options] [prompt]
+
+Options:
+  -p, --prompt <text>          Non-interactive prompt (headless mode)
+  -m, --model <model>          Model to use (e.g., gemini-2.5-pro)
+  --output-format <format>     Output format: text (default), json, stream-json
+  --include-directories <dirs> Comma-separated extra directories to include
+  --yolo                       Auto-accept all tool actions (no confirmations)
+  --resume <session-id>        Resume a previous session
+  --system-prompt <text>       Override system prompt
+  --raw-output                 Disable ANSI codes in output
+  --debug-log <path>           Write debug JSONL log to file
+  -v, --version                Show version
+  -h, --help                   Show help
+```
+
+## Slash Commands (interactive session)
+
+### General
+
+| Command | Description |
+|---|---|
+| `/help` | Show all available commands |
+| `/quit` or `/exit` | Exit Gemini CLI |
+| `/clear` | Clear the current conversation |
+| `/bug` | Report a bug directly from CLI |
+| `/stats` | Show token usage statistics |
+
+### Tools
+
+| Command | Description |
+|---|---|
+| `/tools` | List all available tools |
+| `/tools enable <n>` | Enable a specific tool |
+| `/tools disable <n>` | Disable a specific tool |
+
+### MCP Servers
+
+| Command | Description |
+|---|---|
+| `/mcp list` | List all configured MCP servers |
+| `/mcp status` | Detailed status of all MCP connections |
+| `/mcp enable <n>` | Enable a disabled MCP server |
+| `/mcp disable <n>` | Disable an MCP server (without removing) |
+
+### Chat / Sessions
+
+| Command | Description |
+|---|---|
+| `/chat save <name>` | Save current conversation |
+| `/chat resume <name>` | Resume a saved conversation |
+| `/chat list` | List saved conversations |
+
+### Memory
+
+| Command | Description |
+|---|---|
+| `/memory add <text>` | Add a persistent fact to GEMINI.md |
+| `/memory show` | Display current memory contents |
+| `/memory clear` | Clear all memory entries |
+
+### Checkpointing
+
+| Command | Description |
+|---|---|
+| `/restore` | List available checkpoints |
+| `/restore <filename>` | Restore a specific checkpoint |
+
+### Extensions
+
+| Command | Description |
+|---|---|
+| `/extension list` | List installed extensions |
+| `/extension enable <n>` | Enable an extension |
+| `/extension disable <n>` | Disable an extension |
+
+### Theme
+
+| Command | Description |
+|---|---|
+| `/theme` | Show current theme |
+| `/theme <name>` | Switch to a different theme |
+
+## Built-in Tools (available to the model)
+
+| Tool | Description |
+|---|---|
+| `read_file` | Read file contents |
+| `write_file` | Write/create files |
+| `replace` | Replace text in files (old_string → new_string) |
+| `list_directory` | List directory contents |
+| `glob` | Find files by pattern |
+| `search_file_content` | Search within files by pattern |
+| `run_shell_command` | Execute shell commands |
+| `google_web_search` | Search the web (Google Search grounding) |
+| `web_fetch` | Fetch URL content |
+
+## @ Reference Syntax
+
+In any prompt, reference files and URLs:
+
+```
+@./relative/path.py         # include file content
+@/absolute/path.txt         # absolute path
+@https://example.com        # fetch URL content
+@./folder/                  # include directory listing
+```
+
+Works in both interactive and headless mode:
+```bash
+gemini -p "Review @./src/auth.py for security issues"
+gemini -p "Summarize @https://github.com/org/repo/README.md"
+```
+
+## Keyboard Shortcuts (interactive mode)
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+C` | Cancel current operation |
+| `Ctrl+D` | Exit |
+| `Ctrl+Y` | Toggle YOLO mode (auto-accept tools) |
+| `Ctrl+L` | Clear screen |
+| `↑ / ↓` | Navigate input history |
+| `Tab` | Autocomplete slash commands |
+
+## gemini mcp CLI Commands (outside session)
+
+```bash
+gemini mcp add <n> --command "<cmd>"
+gemini mcp list
+gemini mcp remove <n>
+```
+
+## gemini extension CLI Commands (outside session)
+
+```bash
+gemini extension install <url>
+gemini extension list
+gemini extension remove <n>
+```

package/src/skills/gemini-cli/references/configuration.md

@@ -0,0 +1,182 @@
+# Configuration Reference
+
+## File Locations
+
+| File | Purpose |
+|---|---|
+| `~/.gemini/settings.json` | Global user settings |
+| `<project>/.gemini/settings.json` | Project-level settings (overrides global) |
+| `~/.gemini/GEMINI.md` | Global persistent memory/context |
+| `<project>/GEMINI.md` | Project context (loaded automatically) |
+| `<project>/.gemini/GEMINI.md` | Alternative project context location |
+| `~/.gemini/.env` | Global API key env file |
+| `./.gemini/.env` | Project-level env file |
+| `<project>/.geminiignore` | Files/dirs to exclude from Gemini tools |
+
+## settings.json — Full Schema
+
+```json
+{
+  // Model selection
+  "model": "gemini-2.5-pro",
+
+  // UI theme: "dark" | "light" | "auto" | custom theme name
+  "theme": "dark",
+
+  // Auto-accept all tool confirmations (like --yolo)
+  "autoAccept": false,
+
+  // Tools to include (whitelist) — if set, only these are available
+  "coreTools": ["read_file", "write_file", "run_shell_command", "google_web_search"],
+
+  // Tools to explicitly exclude (blacklist)
+  "excludeTools": ["dangerous_tool_name"],
+
+  // Generation parameters
+  "generationConfig": {
+    "temperature": 0.7,
+    "topP": 0.95,
+    "thinkingBudget": 8192
+  },
+
+  // MCP server configurations
+  "mcpServers": {
+    "serverName": {
+      "command": "node",
+      "args": ["./server.js"],
+      "cwd": "./mcp_tools",
+      "env": {
+        "API_KEY": "$MY_ENV_VAR"
+      },
+      "timeout": 15000,
+      "trust": false,
+      "includeTools": ["safe_tool_1"],
+      "excludeTools": ["unsafe_tool"]
+    }
+  },
+
+  // Sandbox settings
+  "sandbox": {
+    "enabled": false,
+    "command": "docker"
+  },
+
+  // Telemetry
+  "telemetry": {
+    "enabled": true
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GEMINI_API_KEY` | Gemini API key (Option 2 auth) |
+| `GOOGLE_API_KEY` | Vertex AI API key (Option 3 auth) |
+| `GOOGLE_GENAI_USE_VERTEXAI` | Set to `true` to use Vertex AI |
+| `GOOGLE_CLOUD_PROJECT` | GCP project ID for Vertex AI |
+| `GEMINI_MODEL` | Override default model |
+| `GEMINI_SANDBOX` | Sandbox type (`docker`, `podman`, etc.) |
+
+## GEMINI.md Context Files
+
+Context files are plain Markdown. They're loaded hierarchically and merged.
+
+```markdown
+# Project Name
+
+## Rules
+- Always use TypeScript strict mode
+- Prefer async/await over .then()
+
+## Architecture
+The project follows a microservices pattern.
+Main services: auth, api, worker.
+
+## Include external files
+@./docs/api-reference.md
+@./src/types/index.ts
+```
+
+**`@` file references** — include any file's content:
+- `@./relative/path.md` — relative to GEMINI.md location
+- `@/absolute/path.js` — absolute path
+
+**Memory commands:**
+```
+/memory add "Staging database is on port 5432"
+/memory show
+```
+(Writes to `~/.gemini/GEMINI.md`)
+
+## .geminiignore
+
+Similar to `.gitignore`. Place in project root.
+
+```
+# .geminiignore
+/node_modules/
+/dist/
+*.log
+*.env
+secret-config.json
+/backups/
+```
+
+Gemini CLI also respects `.gitignore` automatically.
+
+## Model Configuration
+
+```json
+{
+  "generationConfig": {
+    "temperature": 1.0,
+    "topP": 0.95,
+    "topK": 64,
+    "thinkingBudget": 8192,
+    "maxOutputTokens": 8192
+  }
+}
+```
+
+- `thinkingBudget`: controls extended thinking for Gemini 2.5+ models
+- Lower `temperature` = more deterministic output (good for code)
+- Higher `temperature` = more creative (good for writing)
+
+## System Prompt Override
+
+Override the entire system prompt (advanced):
+
+```bash
+gemini --system-prompt "You are a strict TypeScript reviewer. Only respond with code issues."
+```
+
+Or via settings.json:
+```json
+{
+  "systemPrompt": "You are a helpful assistant for Python development."
+}
+```
+
+## Trusted Folders
+
+Control which directories allow shell command execution:
+
+```json
+{
+  "trustedFolders": ["/home/user/projects", "/workspace"]
+}
+```
+
+## Token Caching
+
+Enabled by default for large context files. Reduces costs and latency when GEMINI.md files are large.
+
+```json
+{
+  "tokenCaching": {
+    "enabled": true
+  }
+}
+```