diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml new file mode 100644 index 0000000..f0ab779 --- /dev/null +++ b/.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 diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..161ac45 --- /dev/null +++ b/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 | diff --git a/SKILL.md b/SKILL.md index 6eda213..c73c856 100644 --- a/SKILL.md +++ b/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.