# Ask Gemini > 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. - Skill: `asachit/ask-gemini` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add asachit/ask-gemini` - Raw SKILL.md: https://api.skillmd.com/api/skills/asachit/ask-gemini/raw - Safety review: WARNING (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: ASACHIT (https://skillmd.com/u/asachit) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/asachit/ask-gemini --- # 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 `), run the bundled installer — it creates the `ask-gemini` PATH launcher, checks for the `agy` engine, and reports readiness: ```bash bash /scripts/install.sh # creates the launcher, checks for agy ``` `` 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 ` 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 `** (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 `, `--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/.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: `, `# output: `, `# chain-max: `. 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 `". 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": "" } ``` ### 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//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//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 `- ` 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//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 ""`. 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--.md ``` Format: ```markdown # Gemini: Date: Type: Session: Model: ## Task ## Gemini Response ## Action Items ``` ## 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/.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}}