Improve/skill review optimization

.github/workflows/skill-review.yml

@@ -0,0 +1,13 @@
+name: Skill Review
+on:
+  pull_request:
+    paths: ['**/SKILL.md']
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main

REFERENCE.md

@@ -0,0 +1,26 @@
+# Parameter Reference
+
+Full parameter list for `scripts/gemini_cli_bridge.py`.
+
+## Required
+
+| Parameter | Description |
+|-----------|-------------|
+| `--PROMPT` | Instruction to send to Gemini |
+| `--cd` | Working directory (typically repo root) |
+
+## Optional
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--SESSION_ID` | (new session) | Resume an existing session (uuid) |
+| `--model` | `gemini-3-pro-preview` | Model to use |
+| `--full-access` | off | Enable edit/shell tools (`auto_edit` approval) |
+| `--yolo` | off | Auto-approve all tools (implies `--full-access`) |
+| `--sandbox` | off | Run in sandbox mode (requires Docker) |
+| `--file PATH` | (none) | Focus file to prepend as `@PATH` (repeatable) |
+| `--max-files` | 5 | Cap for auto-extracted focus files |
+| `--no-guardrails` | off | Disable effective-context guardrails |
+| `--effective-context-tokens` | 48000 | Token threshold for context warnings |
+| `--return-all-messages` | off | Return full streamed event list |
+| `--timeout-s` | 1800 | Process timeout in seconds |

SKILL.md

@@ -1,116 +1,75 @@
 ---
 name: collaborating-with-gemini-cli
-description: "Delegates code review, debugging, and alternative implementation comparisons to Google Gemini CLI (`gemini`) via a JSON bridge script (default model: `gemini-3-pro-preview`). Supports headless one-shot and multi-turn sessions via `SESSION_ID`, with conservative defaults for Gemini effective-context constraints (file-scoped, `--no-full-access` by default) while allowing user override."
+description: “Delegates code review, debugging, and alternative implementation comparisons to Google Gemini CLI via a JSON bridge script. Use when the user wants to ask Gemini to review code, get a second opinion from another model, compare implementations with Gemini, use Gemini for debugging, or delegate analysis to Gemini. Supports headless one-shot and multi-turn sessions, defaulting to read-only file-scoped requests with effective-context guardrails.”
 ---
 
 # Collaborating with Gemini CLI
 
-Use this skill when you want a second model (Gemini) to sanity-check a solution, spot edge cases, propose tests, or suggest an alternative implementation approach.
-
-This skill provides a small JSON bridge script that runs `gemini` (Gemini CLI) in non-interactive **headless** mode and returns structured output.
-
-Compared to `collaborating-with-claude-code`, this skill defaults to **read-only** and is optimized for **file-scoped, one-shot** requests to avoid practical effective-context degradation.
+Runs `gemini` (Google Gemini CLI) in headless mode via a JSON bridge script (`scripts/gemini_cli_bridge.py`) and returns structured output. Defaults to **read-only**, **file-scoped** requests with effective-context guardrails.
 
 ## Requirements
 
-- Gemini CLI installed (`gemini --version`).
-  - Install via npm: `npm i -g @google/gemini-cli`
-- Gemini CLI authenticated (Google account login or API key auth, depending on your local setup).
-- Python 3 (to run the bridge script).
+- Gemini CLI installed: `npm i -g @google/gemini-cli`
+- Gemini CLI authenticated (Google account login or API key)
+- Python 3
 
 ## Quick start
 
 ```bash
-python scripts/gemini_cli_bridge.py --cd "/path/to/repo" --PROMPT "Review src/auth/login.py for bypasses; propose fixes as a unified diff."
-```
+# Basic usage
+python scripts/gemini_cli_bridge.py --cd “/path/to/repo” --PROMPT “Review src/auth/login.py for bypasses; propose fixes as a unified diff.”
 
-Recommended (explicit file scope, best for effective context):
-
-```bash
-python scripts/gemini_cli_bridge.py --cd "/path/to/repo" --file "src/auth/login.py" --PROMPT "Review this file for bypasses; propose fixes as a unified diff."
+# Recommended: explicit file scope (best for effective context)
+python scripts/gemini_cli_bridge.py --cd “/path/to/repo” --file “src/auth/login.py” --PROMPT “Review this file for bypasses; propose fixes as a unified diff.”
 ```
 
 ## Multi-turn sessions
 
-Always capture the returned `SESSION_ID` and pass it back on follow-ups:
+Capture the returned `SESSION_ID` and pass it back on follow-ups:
 
 ```bash
-# Start a new session (one-shot by default)
-python scripts/gemini_cli_bridge.py --cd "/repo" --file "src/auth/login.py" --PROMPT "Summarize issues and propose a patch."
+# Start a new session
+python scripts/gemini_cli_bridge.py --cd “/repo” --file “src/auth/login.py” --PROMPT “Summarize issues and propose a patch.”
 
 # Continue the same session
-python scripts/gemini_cli_bridge.py --cd "/repo" --SESSION_ID "uuid-from-response" --PROMPT "Now propose 5 targeted tests for the fix."
+python scripts/gemini_cli_bridge.py --cd “/repo” --SESSION_ID “uuid-from-response” --PROMPT “Now propose 5 targeted tests for the fix.”
 ```
 
-## Access modes
-
-This skill defaults to `--no-full-access` (read-only).
+When `meta.over_effective_context_limit` is `true` in the response, start a **new session** (omit `--SESSION_ID`) and/or reduce the focus scope.
 
-- **Read-only (default)**: `--no-full-access` → maps to `gemini --approval-mode default`
-- **Full access (edits allowed)**: `--full-access` → maps to `gemini --approval-mode auto_edit`
-- **YOLO (auto-approve everything)**: `--yolo` → maps to `gemini --approval-mode yolo`
+## Access modes
 
-Examples:
+Defaults to `--no-full-access` (read-only).
 
-```bash
-# Allow edits (auto-approve edit tools)
-python scripts/gemini_cli_bridge.py --full-access --cd "/repo" --file "src/foo.py" --PROMPT "Refactor for clarity; keep behavior; apply edits."
-```
+| Flag | Gemini approval mode | Use case |
+|------|---------------------|----------|
+| `--no-full-access` (default) | `default` | Read-only review |
+| `--full-access` | `auto_edit` | Allow edits |
+| `--yolo` | `yolo` | Auto-approve everything (dangerous) |
 
 ```bash
-# YOLO mode (dangerous): allow any tool calls without confirmation
-python scripts/gemini_cli_bridge.py --yolo --cd "/repo" --PROMPT "Run tests, fix failures, and apply edits."
+# Allow edits
+python scripts/gemini_cli_bridge.py --full-access --cd “/repo” --file “src/foo.py” --PROMPT “Refactor for clarity; keep behavior; apply edits.”
 ```
 
-## Effective-context guardrails (default ON)
+## Effective-context guardrails
 
-By default the bridge enables conservative guardrails designed for **practical effective context**:
+Enabled by default. Adds a preamble instructing Gemini to **stop and ask** before reading additional files, and encourages file-scoped runs.
 
-- Adds a preamble instructing Gemini to **stop and ask** before reading additional files.
-- Strongly encourages **file-scoped** runs (use `--file` and keep each call small).
-- Uses `--max-files` as a **preference** for “how many files per turn” and as a **cap for auto-extracted files** (only when you did not pass explicit `--file`).
-
-User override options:
-
-- `--file PATH` (repeatable): explicitly decide the focus file set (recommended; not blocked by `--max-files`).
-- `--max-files N`: raise the preferred cap / auto-extraction cap.
-- `--no-guardrails`: disable guardrails (Gemini may read many files; treat like a normal agent).
-
-### Session rotation guidance (effective context)
-
-The bridge exposes Gemini CLI token stats when available:
-
-- `meta.prompt_tokens`: prompt tokens reported by Gemini CLI
-- `meta.over_effective_context_limit`: `true` when `prompt_tokens > --effective-context-tokens`
-
-When `meta.over_effective_context_limit` is `true`, prefer starting a **new session** for the next turn (omit `--SESSION_ID`) and/or reduce the focus scope.
-
-## Parameters (bridge script)
-
-- `--PROMPT` (required): Instruction to send to Gemini.
-- `--cd` (required): Working directory to run Gemini CLI in (typically repo root).
-- `--SESSION_ID` (optional): Resume an existing Gemini CLI session (uuid).
-- `--model` (optional): Defaults to `gemini-3-pro-preview`.
-- `--full-access` / `--no-full-access` (optional): Defaults to `--no-full-access`.
-- `--yolo` (optional): YOLO approval mode (implies full access).
-- `--sandbox` (optional): Run Gemini CLI in sandbox mode (requires Docker). Default: off.
-- `--return-all-messages` (optional): Return the full streamed event list (debugging).
-- `--file PATH` (repeatable): Focus files to prepend as `@PATH` (recommended).
-- `--max-files` / `--no-guardrails` / `--effective-context-tokens`: Guardrail controls (`--max-files` is a preference + auto-extraction cap; it does not block explicit `--file`).
-- `--timeout-s` (optional): Defaults to 1800 seconds.
+- `--file PATH` (repeatable): explicitly set focus files (recommended)
+- `--max-files N`: cap auto-extracted focus files (default: 5; does not block explicit `--file`)
+- `--no-guardrails`: disable all guardrails
 
 ## Output format
 
-The bridge prints JSON:
-
 ```json
 {
-  "success": true,
-  "SESSION_ID": "uuid",
-  "agent_messages": "…Gemini output…",
-  "all_messages": [],
-  "meta": {}
+  “success”: true,
+  “SESSION_ID”: “uuid”,
+  “agent_messages”: “…Gemini output…”,
+  “all_messages”: [],
+  “meta”: {}
 }
 ```
 
-`meta` includes the normalized focus file list and (when available) token stats extracted from Gemini CLI output.
+`meta` includes focus file list and (when available) token stats. See [REFERENCE.md](REFERENCE.md) for the full parameter list.