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 <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 (see Running in the background) with --result-file:

   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.

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

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

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 (see Running in the background) 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 (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

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:

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

{
  "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"

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:

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

~/.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 for version history.

Task: {{ARGUMENTS}}