Ask Gemini

---
name: ask-gemini
description: Use when you want to delegate or parallelize UI/UX design work — redesign, critique, fix, craft, enhance a frontend — to another model while you keep working; when you want a cross-model second opinion on a design, layout, component architecture, or system decision; when the user says "ask gemini" / "use gemini" / "gemini this" or names Gemini; or when the user asks for design/UI/UX feedback or validation even without naming Gemini.
compatibility: "Requires the Antigravity CLI (agy) installed and authenticated, plus bash 4+ and python3. Works on any runtime supporting the Agent Skills standard (Claude Code, Codex CLI, Pi CLI, Copilot CLI, Antigravity)."
license: MIT
metadata:
  version: "0.13.0"
---

# Ask Gemini — Parallel UI/UX Delegation Skill

Hand off UI/UX work — redesign, critique, fix, craft, enhance — to another model and **run it in parallel** while the main session keeps wiring backend and frontend APIs. The `ask-gemini` script shells out to the Antigravity CLI (`agy`), which is multi-model (Gemini Pro/Flash, Claude, GPT-OSS) and has its own subagent/agent system, so a delegated UI task can itself fan out. The script handles all plumbing (sessions, profiles, design context, UUID capture, cleanup) and returns structured JSON. It also serves cross-model second opinions on design and architecture.

**Division of labor: Gemini is the eye, Claude holds the wheel.** Claude reviews and adapts everything Gemini returns before it touches the codebase — Gemini proposes, Claude integrates.

## Cross-Runtime Install

This skill follows the open Agent Skills standard, so it runs under any runtime that supports it: Claude Code, OpenAI Codex CLI, Pi CLI, GitHub Copilot CLI, and Antigravity/Gemini. It is discovered automatically from the cross-runtime dir `~/.agents/skills/ask-gemini/` (and `~/.claude/skills/ask-gemini/` for Claude Code).

**One-command setup.** After the skill folder lands in a skills dir (manually, or via `npx skills add <source>`), run the bundled installer — it creates the `ask-gemini` PATH launcher, checks for the `agy` engine, and reports readiness:

```bash
bash <skill-dir>/scripts/install.sh            # creates the launcher, checks for agy
```

`<skill-dir>` is wherever the skill is installed — e.g. `~/.agents/skills/ask-gemini` or `~/.claude/skills/ask-gemini`. The installer is idempotent; re-run it anytime.

All examples below use the bare `ask-gemini` command, which the launcher puts on PATH.

**Fallback (no launcher):** invoke the script by its absolute path under your runtime's skills dir, e.g. `~/.agents/skills/ask-gemini/scripts/ask-gemini …`.

**Hard dependency:** the Antigravity CLI (`agy`) must be installed and authenticated — it is the engine this skill drives. **You install `agy` yourself**; the installer only checks whether it's present. Install: `curl -fsSL https://antigravity.google/cli/install.sh | bash`, then authenticate once by running `agy` interactively.

## Parallel Delegation (primary use)

The canonical pattern: dispatch a UI/UX task asynchronously, keep working, collect the result when notified.

1. Fire the design task in the background (see *Running in the background*) with `--result-file`:
   ```bash
   ask-gemini \
     --task "redesign the settings page" --mode ui \
     --name settings-redesign --result-file /tmp/settings-redesign.json
   ```
2. Tell the user "Gemini is redesigning the settings page" and **keep going** on your own track — wire the settings API, types, and data fetching.
3. When the background job finishes, read `/tmp/settings-redesign.json`, then integrate — Claude holds the wheel: review, adapt to project patterns, report.

Because `agy` runs its own subagents, one delegated task can cover a whole screen while you cover the backend. Use the existing modes (`ui`, `code-review`, `architecture`, `quick`) and `--chain` workflows below to shape what you delegate; this section only adds the run-it-in-parallel envelope.

### Design Context (automatic)

On every run the script makes sure the delegated model gets the **same project design context**, so output stays consistent across sessions:

- It auto-detects `AGENTS.md` (which `agy` auto-loads) and otherwise auto-discovers and injects the project's design/context docs (DESIGN.md, STYLE_GUIDE.md, `docs/design/*`, `docs/context/CODEBASE-MAP.md` & `DECISIONS.md`, legacy `GEMINI.md`, etc.).
- In `ui` mode it adopts a designer / creative-director persona with an anti-AI-slop ruleset — but it always **follows any project design system or tokens found first**; the global aesthetic is only the fallback when the project defines none.

### Running in the background

To run a delegation asynchronously: in Claude Code, use the Bash `run_in_background` option; in other runtimes, append `&`. Pair it with `--result-file <path>` and pick up the result when notified.

### Parallel fan-out (large tasks)

For a large multi-surface task, split it into independent units and run one delegation per unit at once — a grid, not a queue. Give each delegation a unique `--name` and a unique `--result-file`, fire them in the background (see *Running in the background*), and collect each as it finishes.

```bash
for screen in dashboard settings billing profile; do
  ask-gemini --task "redesign the $screen screen" --mode ui \
    --name "redesign-$screen" --result-file "/tmp/redesign-$screen.json" &   # other runtimes; Claude Code: run_in_background
done
```

This composes across two levels: several Claude agents can each fan out several `ask-gemini` delegations, so a 12-screen redesign runs as a grid of concurrent work.

Guardrails:
- **Unique `--name` and `--result-file` per delegation.** Shared names collide; shared result-files overwrite.
- **Keep each unit independent** — no shared session. Reserve a single shared `--name` only when you genuinely want threaded follow-ups on that one topic.
- Concurrent *fresh* delegations are safe to resume: each captures a distinct conversation id (race-safe as of 0.13.0), so follow-ups never cross-wire.

## Leveraging agy

`agy` ships its own design MCP tools. In `ui` mode the prompt tells the delegated session to use them for **real assets instead of placeholders** (verified in agy's headless `-p` mode):

- **`hugeicons`** — real icons instead of emoji/SVG stubs.
- **`stitch`** — design systems and full screen mockups.
- **`nanobanana`** — image generation.
- **`lottiefiles-creator`** — animations.

**`--scope <dirs>`** (comma/space-separated dir list) injects a prompt-level constraint telling agy to only create/edit files under those dirs — useful for delegating UI work in parallel while you keep editing other areas. **Honest caveat: this is advisory / prompt-level, NOT OS-enforced.** agy's hooks (which would enforce it) do **not** fire in headless `-p` mode as of agy 1.0.10, so it relies on the model cooperating. If Google fixes headless hooks, it can be upgraded to a real PreToolUse enforcement hook.

## Quick Reference

```bash
# UI/UX task (default)
ask-gemini --task "redesign the watchlist card" --name watchlist

# Code review (read-only)
ask-gemini --task "review this auth logic" --mode code-review --name auth-review

# Quick question (no session needed)
ask-gemini --task "is this accessible?" --mode quick

# Follow-up — just reuse the name, script auto-resumes the agy conversation
ask-gemini --task "now add hover states" --name watchlist

# Resume from previous conversation (any name)
ask-gemini --task "continue the portfolio redesign" --resume-latest

# List active named sessions
ask-gemini --list-sessions

# Specific model
ask-gemini --task "quick check" --model flash --mode quick

# Force fresh session on existing name
ask-gemini --task "start over on watchlist" --name watchlist --fresh

# Scope a delegated redesign to frontend/ while the main session edits elsewhere
# (advisory prompt-level constraint — see "Leveraging agy")
ask-gemini --task "redesign the dashboard" --mode ui --name dashboard --scope frontend/

# Async / parallel delegation — see "Parallel Delegation (primary use)" above
# Run in the background (see "Running in the background") + --result-file, pick up result when notified

# Large prompt via stdin (--task -)
cat docs/long-prompt.md | ask-gemini --task - --name big-prompt

# Chain with continue-on-failure (don't abort on first step failure)
ask-gemini --step "lint" --step "test" --step "deploy" \
  --name ci-chain --continue-on-failure

# Resume a chain from a specific step (reuses stored UUID)
ask-gemini --step "lint" --step "test" --step "deploy" \
  --name ci-chain --resume-step 3
```

## How to Invoke

### Step 1: Parse user intent

From the user's request, determine:
- **Task**: the actual question/instruction for the model
- **Mode**: `ui` (design work), `code-review`, `architecture`, `quick` (sanity check)
- **Name**: pick a short descriptive name for the session (e.g., `watchlist`, `auth-review`, `portfolio-chart`). Use the same name for follow-ups on the same topic.
- **CLI flags**: `--model <model>`, `--sandbox` get forwarded

### Step 2: Invoke the script

Run a **single Bash call**:

```bash
ask-gemini \
  --task "the actual task text" \
  --mode ui \
  --name "watchlist-redesign"
```

For follow-ups on the same topic, reuse the same `--name` — the script auto-resumes the agy conversation:
```bash
ask-gemini \
  --task "now add hover states" \
  --name "watchlist-redesign"
```

To check what sessions exist: `ask-gemini --list-sessions`

For long tasks (page design, deep review), run it in the background (see *Running in the background*) and collect `--result-file` when done:
```bash
ask-gemini --task "redesign the entire settings page" --mode ui --result-file /tmp/gemini-result.json
```
Then tell the user "Gemini is working on it" and pick up `/tmp/gemini-result.json` when notified.

### Step 3: Parse the JSON result

The script returns structured JSON to stdout:

```json
{
  "success": true,
  "exit_code": 0,
  "gemini_uuid": "8a5a400a-48b3-4014-9374-dabf94aaef06",
  "session_id": "4bd0e2ba-0e26-4d4e-84c9-04e297e14735",
  "session_dir": "/Users/.../.ask-gemini/sessions/4bd0e2ba.../",
  "response": "... Gemini's actual response text ...",
  "duration_s": 45,
  "resumed": false,
  "mode": "ui",
  "approval": "",
  "timeout": 180,
  "profile": "web-app-frontend",
  "context_mode": "direct",
  "stderr_excerpt": ""
}
```

**Store `session_id` mentally** for follow-up calls in the same conversation.

### Step 4: Process the response

1. **Check `success`** — if false, check `stderr_excerpt` and `exit_code` for diagnostics
2. **Read `response`** — this is Gemini's output
3. **Evaluate critically (Claude holds the wheel).** Verify every design-system claim Gemini made against the project's tokens / DESIGN.md before integrating, and reject whatever conflicts.
4. **Adapt to codebase** — Gemini won't know exact imports, cn() usage, or project patterns. Translate.
5. **Report to user** — Summarize what Gemini suggested, what you kept/modified and why.

## Mode Reference

| Mode | Approval | Idle / Max | Context? | Use When |
|------|----------|------------|----------|----------|
| `ui` / `auto` | n/a | 180s / 900s | yes | Component design, layout, styling |
| `code-review` | n/a | 120s / 600s | no | Logic review, architecture opinion |
| `architecture` | n/a | 120s / 600s | no | System design, API design |
| `quick` | n/a | 60s / 300s | no | Sanity checks, quick questions |

Antigravity has no approval modes — the script always auto-approves via `--dangerously-skip-permissions` in headless mode. The `--approval` flag is kept for backward compatibility but is now a NO-OP.

Activity detection uses 4 signals: stdout size, stderr size, agy conversations dir changes, and PID CPU time. Idle timer only ticks when all 4 are flat — so model thinking or buffered tool-calls won't trigger premature kills.

## Models

`--model` takes Antigravity model names. Default is **Gemini 3.1 Pro (High)**. The script accepts two friendly shorthands:

- `flash` → "Gemini 3.5 Flash (High)"
- `pro` → "Gemini 3.1 Pro (High)"

Available models (from `agy models`): Gemini 3.5 Flash (Low/Medium/High), Gemini 3.1 Pro (Low/High), Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium). Pass any of these full names to `--model`, or use a shorthand above.

## Session Lifecycle

Sessions are tracked by **name** — a short human-readable label the calling agent picks based on the topic.

1. **First call on a topic**: Pick a descriptive name → `--name watchlist-redesign`. Script creates a new session, runs agy, captures UUID.
2. **Follow-up on same topic**: Reuse the same name → `--name watchlist-redesign`. Script auto-resumes the agy conversation via stored UUID.
3. **Different topic in same conversation**: Pick a different name → `--name auth-review`. Separate agy conversation, no cross-contamination.
4. **Cross-conversation resume**: `--resume-latest` picks up the most recent session. Or use the same `--name` — named sessions persist across conversations.
5. **Fresh start**: `--name watchlist-redesign --fresh` creates a new session under that name, replacing the old one.
6. **Quick one-offs**: Omit `--name` entirely for throwaway questions that don't need resume.

**How to pick names:** Use the topic, not the action. `watchlist` not `call-1`. `portfolio-chart` not `tuesday-session`. Names are kebab-case, short, and topical.

## Chain System (Multi-Step Tasks)

**Iterative chains, same session, history-aware.** Each step is a separate agy call that resumes the prior step's conversation UUID. The model sees every previous step's response in its conversation history naturally — no manual context passing. Use chains when step N's work depends on step N-1's actual output (ideate→pick→build, find→fix→verify).

Trade: wall time ≈ sum of step durations (vs single call for one task). For long chains, run it in the background (see *Running in the background*) and collect `--result-file` when done.

### Inline steps:
```bash
ask-gemini \
  --step "Ideate 5 approaches for the watchlist card" \
  --step "Pick the best one and explain why" \
  --step "Implement it with full production code" \
  --output last \
  --name watchlist-chain \
  --mode ui
```

### Chain templates (reusable workflows):
```bash
# Use a saved template — {TASK} gets replaced
ask-gemini --chain ideate-and-build --task "watchlist card redesign" --name watchlist

# List available templates
ask-gemini --list-chains
```

### Available chain templates:

| Template | Steps | Use When |
|----------|-------|----------|
| `ideate-and-build` | Ideate → Pick winner → Implement | New feature design |
| `design-critique` | Score design → Propose fixes → Implement fixes | Improving existing UI |
| `review-and-fix` | Find issues → Fix them → Verify | Code/design review |
| `explore-and-spec` | Research → Compare approaches → Write spec | Pre-implementation planning |
| `refactor` | Analyze → Plan changes → Execute refactor | Code cleanup |

### Output modes:

| `--output` | Returns |
|------------|---------|
| `last` (default) | Only final step's output |
| `all` | Every step with `## Step N` headers |
| `summary` | First paragraph (up to first blank line, max 500 chars) per intermediate step + full final step |

### Creating custom chains:

Save to `~/.ask-gemini/chains/<name>.chain`:
```
# Description of what this chain does
# mode: ui
# output: all
# chain-max: 1800
First step instruction. Use {TASK} for the user's task.
---
Second step instruction.
---
Final step instruction.
```

Steps separated by `---`. The leading comment block (lines starting with `# `) can carry:
- A free-form description (first `# ` line, no key).
- **Directives**: `# mode: <ui|code-review|architecture|quick>`, `# output: <last|all|summary>`, `# chain-max: <seconds>`.

Caller-passed flags (`--mode quick`, `--output last`, `--chain-max 60`) always win over template directives — directives only apply when the caller didn't override. `{TASK}` placeholder replaced at runtime.

### When to use chains vs single tasks:

- **Single task**: Quick questions, code reviews, one-shot design work
- **Chain**: Iterative workflows where step N depends on step N-1 (ideate→build, review→fix, analyze→refactor)

### Timeout behavior:

- **Per-step idle/max**: each step uses the mode's idle/max timeout independently (idle counter resets at each step boundary, since it's a new agy invocation).
- **Overall cap (`--chain-max`, default 3600s)**: total wall time across all steps. Prevents runaway chains.
- For very large chains, run it in the background (see *Running in the background*) and collect `--result-file` when done.

### Failure handling:

**Default (abort-on-failure).** If a step fails (non-zero exit, timeout, or chain_max breach), the chain aborts and returns what completed. JSON includes `failed_step` (1-based idx), `chain_steps_completed`, and the partial `response`.

**Continue-on-failure** (`--continue-on-failure`). Record the failure but advance to the next step. Useful for independent steps (e.g., lint → test → deploy where you want all three reports). Final `success` is `true` if any step succeeded; `false` only when every step failed. `failed_step` is the FIRST failing step.

**Resume from a specific step** (`--resume-step N`). After a failure, you can fix the underlying issue (or the prompt) and continue the chain from step N — without re-running steps 1..N-1. Requires `--name X` (the named session must already hold a stored agy UUID from a prior run). Steps before N are kept as preserved history (their `step-{i}-response.txt` files are included in `--output all`/`summary` aggregation but not re-executed).

Semantics: `--resume-step N` means "skip steps 1..N-1, resume the stored agy conversation, run steps N..end with `--conversation <uuid>`". One-flag recovery from a mid-chain failure.

### JSON output fields (chains):

```json
{
  "is_chain": true,
  "chain_steps_total": 3,
  "chain_steps_completed": 2,
  "failed_step": 3,         // null on full success
  "chain_max": 3600,
  "steps": [
    {"idx": 1, "duration_s": 45, "exit_code": 0, "timeout_reason": "", "response_preview": "..."},
    {"idx": 2, "duration_s": 62, "exit_code": 0, "timeout_reason": "", "response_preview": "..."},
    {"idx": 3, "duration_s": 30, "exit_code": 124, "timeout_reason": "idle", "response_preview": ""}
  ],
  "gemini_uuid": "<shared across all steps>"
}
```

### Inspecting chains:

`--dry-run` prints every per-step prompt before invocation, so you can verify framing and `{TASK}` substitution without burning agy calls.

## Profiles

The script auto-loads profiles from `~/.ask-gemini/profiles/<project-name>/profile.conf` based on the current directory name. Profiles define:
- `context_files` — which files Gemini should read for context
- `project_desc` — project description for the system prompt
- `role` — Gemini's role in the prompt
- `design_rules_file` — optional per-project design rules (path relative to profile dir). This is a project-specific layer that **stacks on top of** the always-injected global ruleset (see Design Rules below), not a replacement for it.
- `default_mode` — default mode when not specified
- `context_mode` — `direct` (Gemini reads files) or `relay` (inline in prompt)

To add a new project, create `~/.ask-gemini/profiles/<project-name>/profile.conf`.

## Design Rules (global, learnable)

A global design ruleset lives at `~/.ask-gemini/design-rules.md`. It ships with sensible defaults (anti-AI-slop rules, how-to-approach, craft details) and is **always injected** into every `ui`/`auto` (design) delegation under the heading `## Design Rules (always follow)`. It is seeded on install / first run and never overwritten — the file is yours to edit by hand.

The per-project `design_rules_file` (in a profile) stacks on top of this global file; the global rules are the floor, the project file adds specifics.

### Teaching it new rules: `ask-gemini --learn "rule"`

```bash
ask-gemini --learn "Never use drop shadows on cards"                  # global (default)
ask-gemini --learn "Use the brand serif for page titles" --scope project
```

This appends `- <rule>` under the `## Learned rules` heading (newest at the bottom). Re-running with the same text is a no-op (`action:"already-known"`). Output is JSON: `{"success":true,"action":"learned","scope":"global","rule":"...","file":"..."}`.

**Scope (`--scope global|project`):**
- `global` (default) — writes the shared `~/.ask-gemini/design-rules.md`; applies to every project.
- `project` — writes a per-project file at `~/.ask-gemini/profiles/<project-key>/design-rules.md` (holds only that project's learned rules). It is injected into ui/auto prompts under `## Project Design Rules (learned)`, stacking on top of the global rules.

**Cap + warning:** once a rules file has more than 20 learned rules, `--learn` still keeps the rule (never lossy) but adds a `"warning"` field suggesting you prune (`--list-rules`) or promote rules into the curated body.

### Reviewing and maintaining rules

- `ask-gemini --list-rules [--scope global|project|all]` — prints the rules (human-readable markdown, not JSON) so you can read and prune by eye. Default scope is `all`.
- `ask-gemini --update-defaults` — pulls newer curated rules shipped with the skill into your global file **without touching your learned rules**. Backs up the old file to `design-rules.md.bak` first. Run this after upgrading the skill.

**Instruction for the orchestrating model (Claude):** When the user states a *durable* design do/don't — e.g. "tell gemini to never X", "always do Y in designs", or corrects a delegated design result with a general preference — persist it by calling `ask-gemini --learn "<imperative rule>"`. Phrase the rule as an imperative ("Never use drop shadows on cards", "Always use tabular numbers in tables"). Use `--scope project` when the preference is clearly specific to the current project (its brand, its components, its conventions); use the default `--scope global` for universal taste that should apply everywhere. Skip one-off, task-specific instructions — only capture preferences meant to apply to future design work.

## Context Modes

- **`direct`** (default): Script tells Gemini to read design files itself. The calling agent never touches them. Lightest on the calling agent's tokens.
- **`relay`**: Script inlines file contents into the prompt. Heavier but guarantees Gemini sees the context. Use when Gemini fails to read files in `direct` mode.

## Error Handling

The script handles errors internally and returns them in the JSON:
- `success: false` + `exit_code: 124` → Gemini timed out
- `success: false` + `exit_code: 1` → Gemini error (check `stderr_excerpt`)
- `gemini_uuid: ""` → UUID capture failed (session resume won't work for follow-ups)

For debugging, check:
1. `stderr_excerpt` in the JSON response
2. `$session_dir/stderr.log` for full stderr
3. `$session_dir/prompt.md` for what was sent
4. `~/.ask-gemini/debug/last-error.log` for last failure

## Artifact Saving

After every Gemini invocation, save to:
```
docs/gemini-artifacts/gemini-<slug>-<YYYYMMDD-HHmm>.md
```

Format:
```markdown
# Gemini: <Task Title>
Date: <timestamp>
Type: <ui-ux | code-review | architecture | general>
Session: <fresh | resumed (UUID: xxx)>
Model: <default | user-specified>

## Task
<What was asked>

## Gemini Response
<Raw response from JSON result>

## Action Items
<What the calling agent will do with this response>
```

## Missing Binary

If `agy` is not found when the script runs, it will fail with a non-zero exit code. Tell the user:
"Antigravity CLI (`agy`) required. Install: `curl -fsSL https://antigravity.google/cli/install.sh | bash` (installs `agy` to `~/.local/bin/agy`)."

**First-time auth:** headless use needs a one-time login — run `agy` once interactively to authenticate, after which it works headless. (On the dev's machine it's already authed and reuses `~/.gemini`.)

## Known Limitations

- **Per-step idle timeout in chains resets at each step boundary** — this is intentional (each step is a new `agy` invocation), but a chain with N steps in `ui` mode can run up to N × 900s in the worst case unless `--chain-max` caps it. Default `--chain-max 3600`.
- **`--sandbox` is forwarded but not exercised by the test suite.** Sandbox-mode integration testing is deferred to a follow-up.

The old basename-collision limitation (the previous engine keyed its state dir by `basename(pwd)`, cross-contaminating projects sharing a directory name) was **resolved by the agy migration**: agy stores one SQLite db per conversation at `~/.gemini/antigravity-cli/conversations/<uuid>.db`, which is not basename-keyed.

## Tests

Local bats suite under `tests/`. Run with:

```bash
~/.claude/skills/ask-gemini/tests/run-tests.sh
# or single file:
~/.claude/skills/ask-gemini/tests/run-tests.sh ~/.claude/skills/ask-gemini/tests/04_chain.bats
```

The harness vendors bats-core to `tests/.bats/` on first run; subsequent runs reuse it. A deterministic `mock-agy` stub shadows the real CLI for test runs (no network, no LLM calls).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

Task: {{ARGUMENTS}}