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.

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 <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 (Claude Code: Bash run_in_background; other runtimes: append &) and collect --result-file when done:

   ask-gemini \
     --task "redesign the settings page" --mode ui \
     --name settings-redesign --result-file /tmp/settings-redesign.json

1. Tell the user "Gemini is redesigning the settings page" and keep going on your own track — wire the settings API, types, and data fetching.
2. When the background job finishes, read /tmp/settings-redesign.json, then integrate (evaluate critically, 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.

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

# 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 (Claude Code: Bash run_in_background; other runtimes: append &) + --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:

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:

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 (Claude Code: Bash run_in_background; other runtimes: append &) and collect --result-file when done:

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:

{
  "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 — Gemini may violate the design system. Cross-check key decisions.
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

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 (Claude Code: Bash run_in_background; other runtimes: append &) and collect --result-file when done.

Inline steps:

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):

# 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:

Output modes:

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 (Claude Code: Bash run_in_background; other runtimes: append &) 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):

{
  "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 — path to design rules (relative to profile dir)
• 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.

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:

# 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.
• No approval modes. Antigravity has none — agy always runs with --dangerously-skip-permissions in headless mode. The --approval flag is kept as a no-op for back-compat.

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:

~/.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

0.10.0 (2026-06-19)

• ui mode now surfaces agy's design MCP tools (hugeicons/stitch/nanobanana/lottiefiles) for real assets; added --scope <dirs> prompt-level edit constraint for safe parallel delegation (advisory — agy headless hooks don't fire in 1.0.10).

0.9.0 (2026-06-19)

• Bundled installer scripts/install.sh — one-command setup on any machine/runtime: creates the ask-gemini PATH launcher, checks for agy (does not install it), verifies readiness. Idempotent.
• Cross-Runtime Install section now leads with the one-command installer (pairs with npx skills add).

0.8.0 (2026-06-19)

• Cross-runtime portable — works under Codex CLI, Pi CLI, Copilot CLI, and Antigravity via ~/.agents/skills, not just Claude Code.
• PATH-launcher command — replaced hardcoded ~/.claude/... script paths with the bare ask-gemini command.
• Cross-Runtime Install section added (install dir, PATH launcher one-liner, fallback, agy dependency).
• Generalized Claude-specific phrasing — run_in_background and /ask-gemini now described runtime-neutrally.
• Frontmatter — added compatibility and metadata.version.

0.7.0 (2026-06-19)

• Fixed context regression — script now auto-loads AGENTS.md (which agy auto-loads), not the retired GEMINI.md.
• Cross-session consistency — design context is re-discovered on every run, so multiple sessions feed the model the same context.
• Expanded discovery — injects docs/context/* (CODEBASE-MAP, DECISIONS), .claude/DESIGN.md, and legacy GEMINI.md explicitly.
• `ui` mode persona — adopts a designer / creative-director persona with an anti-AI-slop ruleset; still follows project design system/tokens first.
• Description rewritten for discovery — reframed around WHEN to use (SDO), not what it does.
• Parallel delegation documented as the primary use — async UI/UX handoff via run_in_background + --result-file.

0.6.0 (2026-06-19)

Migrated engine from Gemini CLI (gemini, retired 2026-06-18) to Antigravity CLI (agy).

• Binary — gemini → agy (installed at ~/.local/bin/agy).
• Resume — -r <uuid> → --conversation <uuid> (headless resume + memory persistence verified).
• Auto-approve — --approval-mode yolo → --dangerously-skip-permissions; the --approval flag is now a no-op.
• Output — stays plain text on stdout (no JSON parsing).
• Conversation store — moved to ~/.gemini/antigravity-cli/conversations/<uuid>.db; the basename-collision limitation is resolved (the store is no longer keyed by basename(pwd)).
• Default model — now Gemini 3.1 Pro (High); flash/pro shorthands map to Antigravity model names.
• Public flags unchanged — --task, --name, --mode, --chain, --step, --resume-latest, etc. all behave as before.

0.5.0 (2026-05-17)

• Test coverage — bats harness with mock-gemini stub. 58 tests across arg parsing, sessions, profiles, chains, resilience flags, and UX polish.
• `set -e` enabled — every existing || true site audited and classified (see docs/v0.5-set-e-audit.md). No bug-masking sites found; all are intentional cleanup.
• `--task -` — read task body from stdin. Useful for long prompts and pipelines.
• Chain template directives — leading # mode:, # output:, # chain-max: lines in .chain files set defaults. Caller flags still win.
• `--continue-on-failure` — chains advance past failed steps instead of aborting. Final success is true if any step succeeded.
• `--resume-step N` — resume a chain from step N, reusing the stored Gemini UUID. Steps 1..N-1 are preserved (not re-executed).
• `--preview-bytes N` — configurable per-step response_preview cap in JSON output (default 300).
• `--output summary` improvement — keeps the first paragraph (up to first blank line, capped 500 chars) of intermediate steps instead of collapsing to the first line.
• `--list-sessions` chain previews — read from step-1-prompt.md when present, so the preview shows the actual first task instead of the placeholder "Chain: foo (3 steps)".
• Per-step stderr cleanup — chain runs delete per-step stderr files after concatenating into the canonical stderr.log. --debug preserves them for inspection.
• Auto-generated profile fix — default_mode=ui instead of default_mode=auto (the latter caused circular re-resolution).
• Known limitations documented — Gemini's basename-keyed chats dir collision surfaced explicitly.

0.4.0

• Iterative chains — each step is a separate Gemini call resuming the prior step's session UUID. Model sees prior responses in conversation history naturally. Replaced the v0.3 mega-prompt approach.
• `--chain-max` — overall chain timeout cap (default 3600s).
• `--dry-run` — print the would-be prompt(s) and exit without invoking Gemini.
• `--debug` — per-poll monitor signals to stderr for diagnosing stuck calls.
• `--version` — print version and exit.
• Improved idle detection — 4-signal activity check (stdout size, stderr size, Gemini chats dir mtime+size, PID CPU time). Long model thinks no longer trigger false idle timeouts.
• Bug fixes: macOS realpath -m replaced with python; cleanup no longer deletes named sessions; flock on named-session creation; project basename hash isolation for ask-gemini's own state; UUID capture scans every JSONL line, not just the first.

Task: {{ARGUMENTS}}