agentleFS
khoa-nakhoa-na/antigravity-mcp/.claude/skills/antigravity/SKILL.md

antigravity

Skill0 starsChanged 2 days agoMITView on GitHub

Delegate a bounded coding task to the Google Antigravity agent (Gemini, via the `agy` CLI) by running `agy -p` as a background worker. Use only when the user explicitly asks to use Antigravity, Gemini or agy as a second coding agent. Do not use it for tasks you can just do yourself.

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use codex.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • engtySkill

    codex

    Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 6 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Treat each run as a background worker that you manage through the agy CLI, no Claude sub-agent in between:

    line 14
  2. Very specific:

    Not every level exists for every model.

    line 55
  3. Distinctive:

    Never put secrets or tokens in the prompt.

    line 66
  4. Distinctive:

    Never run two workers in the *same* directory: nothing locks it.

    line 67
  5. Very specific:

    When the user asks to read or load the folder with Antigravity, read it yourself too, and have agy build its own picture in the directory's …

    line 79
  6. Very specific:

    Run it like any other run (background, <model-flags> from the worker flags, state file as under "Follow-ups"), record the conversation_id, …

    line 85
  7. Distinctive:

    Write the task to a file outside the repo (a temp dir.

    line 91
  8. Very specific:

    Start the process in the target repo or worktree: that makes it the agent's working directory, as when a person runs agy there.

    line 105
  9. Very specific:

    Before a run read it; if the directory has an entry, add --conversation <id> with the worker flags.

    line 167
  10. Very specific:

    After reading the result, write the returned conversation_id back (nothing if it is empty).

    line 168
  11. Very specific:

    One agy process per conversation at a time: never resume it (as worker or advisor) while a background run on it is still going.

    line 173
  12. Distinctive:

    No group matches: say so and carry on cautiously.

    line 201
  13. Very specific:

    Before a task, and again every two or three steps of a multi-step task, check the bucket for the model you use.

    line 206
  14. Very specific:

    If a run ends with status: ERROR whose text mentions quota, exhausted, rate limit or 429, treat it as a quota failure: run the check, …

    line 212
  15. Distinctive:

    After every run, regardless of status or hooks (other harnesses do not run them):

    line 238
  16. Distinctive:

    Run the project's tests/linters yourself.

    line 240

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Antigravity coding agent

agy -p runs the Antigravity CLI agent once, headless, with Read/Write/Bash tools. It is the same agent a person gets by typing agy in a terminal, with these differences: one prompt, one turn, no way to ask you questions mid-run, and no permission prompts.

Treat each run as a background worker that you manage through the agy CLI, no Claude sub-agent in between:

You wantHow agy gives it
Runs while you keep talking to the userBash run_in_background: true; you are notified when it exits
Your context stays cleanThe brief makes agy end with a short report; you read only that
Several workers at onceOne run per repo or worktree (different directories work in parallel)
Isolated changesgit worktree: the worker edits a throwaway checkout (see "Isolated run")
Follow-up with the worker's memory--conversation <id>
An independent checkA second, read-only agy run on the diff (see "Second opinion")

Task from the user: $ARGUMENTS

Configuration (edit only here)

The model and reasoning level this skill uses are declared here and nowhere else. The user chooses them each time (ask: each-use); the values below are only the suggested defaults:

model:  gemini-4-hydrogen
effort: medium
ask:    each-use
  • ask: each-use: the first time in a session that you use agy as worker (or to prime), and the user's request does not already name a model and level, ask the user which to use (the ask tool if you have one, otherwise a chat question) before running. Offer the families from agy models, the values above as the recommended option, and only the levels that exist for the chosen family. Store the answer under worker in agy-session.json; later calls reuse it without asking. The user may change it any time: that is just different flags on the next call, not a new conversation (verified: the model switches on resume). ask: never uses the values above silently. With nobody to ask (a headless run), use the values above and say so.
  • model: a model family from agy models (the ID without its trailing level, for example gemini-4-hydrogen), a full ID such as gemini-4-hydrogen-medium, or default to use the model configured in agy itself.
  • effort: low, medium, high, xhigh, max, or default. Leave it default when model is a full ID that already ends in a level: the two conflict.
  • Build <model-flags> from them: --model <model> --effort <effort>, leaving out any that is default. Use <model-flags> wherever the commands below show it. If the user names another model or level in their request, use theirs for this run only.
  • Not every level exists for every model. An unsupported pair fails with invalid model selection ... (available: ...) (exit 1, no response). Do not guess or retry with another model: tell the user which levels are available so they can edit this block.

Safety first

  • --dangerously-skip-permissions is required for tasks (headless mode cannot prompt; without it, shell commands in a workspace agy does not trust are silently denied and you get an empty reply). So the agent can run any command and edit any file the OS lets it. Only delegate tasks the user asked for, in a repo whose changes are recoverable (clean git status first, or use an isolated worktree, or say it is not).
  • Explicit deny rules still apply under that flag (verified); see "Second opinion" for the syntax.
  • Never put secrets or tokens in the prompt.
  • Never run two workers in the same directory: nothing locks it. Different directories are fine (verified).

Check it works (once)

agy models

Lists the model IDs (first column) and proves agy is installed and logged in. If the command is not found or errors, say so and stop; do not guess a path. If it says the account must be verified, that is the user's to do.

Prime: read the folder together (start of a session)

When the user asks to read or load the folder with Antigravity, read it yourself too, and have agy build its own picture in the directory's conversation, read-only and facts only:

cd /abs/path/to/repo && agy -p "Read this repository: layout, entry points, conventions, how to run the tests, anything fragile. You cannot and must not edit files or run commands. Reply in at most 40 lines of FACTS only: no opinions, no recommendations, no plan." <model-flags> --dangerously-skip-permissions --settings '{"permissions":{"deny":["command(*)","write_file(*)"]}}' --output-format json --print-timeout 600s

Run it like any other run (background, <model-flags> from the worker flags, state file as under "Follow-ups"), record the conversation_id, then tell the user what it found. Compare its summary with what you read; verify any claim you will rely on. Later worker tasks and advisor calls resume this conversation. If it is already primed in this session, do not prime again.

Brief the agent

Write the task to a file outside the repo (a temp dir; long prompts break shell quoting) with:

  1. The task, in one paragraph.
  2. Exact files/dirs it may touch, and files it must not touch.
  3. Constraints (style, no new dependencies, no commits, no network).
  4. Acceptance checks it should run itself (e.g. the test command).
  5. "Read AGENTS.md / GEMINI.md first if present" when the repo has project rules.
  6. The reply format, so its answer is the short report you read instead of a transcript:

    Your final reply must be at most 15 lines of plain text: (a) files you changed, (b) each command you ran with its real result, (c) anything you could not do or are unsure about. No code listings.

Templates (TDD, review, security audit, test generation): references/prompts.md.

Run it

Start the process in the target repo or worktree: that makes it the agent's working directory, as when a person runs agy there.

Do not use --add-dir. It re-roots the agent's working directory to the added directory (verified), so the agent would no longer be "in" the repo, and with a worktree it could end up in the parent folder that holds your other worktrees. It is not needed: under --dangerously-skip-permissions the agent can read the brief and diff files that live outside the repo. On Windows write the paths inside the prompt text as C:/Users/... (forward slashes).

cd /abs/path/to/repo && agy -p "Read /abs/tmp/prompt.md and carry out the task described there. Follow its reply format exactly." <model-flags> --dangerously-skip-permissions --output-format json --print-timeout 900s
  • Run it with the Bash tool's run_in_background: true. Real runs take 100-150 s up to many minutes, longer than the Bash foreground limit (2 min default, 10 min max). Tell the user it started, carry on, and read the result when the completion notification arrives. If your harness has no background mode, run in the foreground with the Bash timeout above --print-timeout.
  • Always pass --print-timeout (Go duration: 900s, 15m) and --output-format json; a hook blocks the call otherwise. The --print-timeout default, 0, waits forever. When it fires, agy stops the turn and its background tasks itself and exits 3 (partial work).
  • Replace <model-flags> with the flags built from "Configuration" (agy models lists the IDs).
  • Git Bash on Windows rewrites a prompt that starts with / into a path. Prefix such commands with MSYS_NO_PATHCONV=1 (needed for the quota command below).

Isolated run (recommended for risky, large or parallel work)

Give the worker its own checkout so your working tree is untouched until you decide:

cd /abs/path/to/repo && git worktree add -b agy/<id> /abs/tmp/agy-<id> HEAD
cd /abs/tmp/agy-<id> && agy -p "..." <model-flags> --dangerously-skip-permissions --output-format json --print-timeout 900s
  • The worktree starts from HEAD: uncommitted changes in the main checkout are not in it.
  • Review the result with git -C /abs/tmp/agy-<id> status --short and git diff, and run the tests there. Bring accepted work back only with the user's OK, e.g. git -C /abs/tmp/agy-<id> diff HEAD > /abs/tmp/agy-<id>.patch && git -C /abs/path/to/repo apply /abs/tmp/agy-<id>.patch.
  • Clean up when the user has accepted or rejected it: git worktree remove --force /abs/tmp/agy-<id> and git branch -D agy/<id> (and delete that directory's entry in agy-session.json). Several workers = several worktrees, each with its own run and its own conversation.

Read the result

Stdout is one JSON object (do not scrape anything else). With the reply format above it is small:

fieldmeaning
statusSUCCESS or ERROR
responsethe agent's final reply: your short report (partial if it was cut off)
error, finished_reasonwhy it failed, e.g. print_timeout, error
conversation_idwrite it to agy-session.json now, every run, even if unchanged (manual and easy to skip); empty if it failed before starting (write nothing)
usage.input_tokenshow long the conversation is. It grew from about 16k after a prime to 244k after a worker, an advisor and three dual-advisor rounds. See "Follow-ups" for when to start fresh.
duration_secondsnot this run's time when you use --conversation: in a 6-step test it read 38, 88, 163, 246, 323 and 2745 s while each call really took 33-86 s (it looks like time since the conversation began). Time the call yourself.

Exit code: 0 success, 1 error (bad model, auth, ...), 2 usage error (unknown or stray argument: no JSON is printed, only a message on stderr), 3 print timeout (partial). A non-zero code makes your shell tool report a failed command: read the JSON anyway. SUCCESS means the turn completed, not that the code is right. After ERROR/3 the tree may be half-edited.

Follow-ups

  • Session continuity (this skill is self-contained; CLAUDE.md is optional): ONE conversation per directory, shared by prime, worker and the advisor (antigravity-advisor), so Gemini keeps what it read. State file: agy-session.json in the session's scratchpad directory (no scratchpad listed: keep it in context only, never a cross-session file), shaped {"<abs dir>":{"id":"<conversation_id>","flags":{"worker":"<model-flags>","advisor":"<model-flags>"}}}. Before a run read it; if the directory has an entry, add --conversation <id> with the worker flags. After reading the result, write the returned conversation_id back (nothing if it is empty). Start fresh only when the user asks for a new agy session, the worktree is removed, the conversation is too long (the last call's usage.input_tokens is about 200,000 or more: offer a fresh one and prime again) or its quota low. Fresh means drop the entry's id but keep its flags, so the user is not asked again. Input grows every turn, so keep follow-ups short.
  • One agy process per conversation at a time: never resume it (as worker or advisor) while a background run on it is still going.
  • Never pass an ID from a different directory: the conversation stays bound to its original directory (verified), so a worktree would edit the old checkout. A worktree is a new conversation without the primed context (prime it again), and when you remove it, drop its entry.
  • --conversation <conversation_id> resumes that exact conversation (preferred: it survives other Antigravity use in between). After exit 3, continue with "Continue and finish the task".
  • --continue resumes the CLI's most recent conversation, global and not per repo. Use it only right after your own run.
  • Pass this role's <model-flags> and the safety flags again on every call; each run is a new process.

Quota

MSYS_NO_PATHCONV=1 agy -p "/quota" --output-format json --print-timeout 30s

Answered by the CLI itself: instant, no model call, no quota spent. Models share a bucket by group, and quota is consumed in proportion to token cost, so long multi-step tasks drain it faster than short ones. Find the bucket for the configured model without assuming anything about model names:

  1. Get the model's display name from agy models (second column, for example Gemini 4 Hydrogen (Medium)) and drop the trailing (...): that is its family name (Gemini 4 Hydrogen). With model: default you cannot know which model agy will use, so look at every group and use the lowest bucket.
  2. In the JSON read command.data.groups[]. A group applies to your model if its name equals the family name, or its description lists it (for example Models within this group: ...).
  3. Each group has buckets[] with name, window (weekly, 5h, ...), remaining_fraction (0 to 1) and reset_time (UTC). The lowest remaining_fraction in the applicable group decides. The tab-separated response field summarises the same numbers but does not say which models belong to which group.
  4. No group matches: say so and carry on cautiously; do not block.

(How groups and windows are arranged changes. When this was written one group had only a weekly bucket and the others had weekly and 5-hour ones. Read them from the output, do not assume.)

Before a task, and again every two or three steps of a multi-step task, check the bucket for the model you use. Suggested thresholds (this skill's judgement, not agy's): 20% or more, go; 5-20%, finish only the current step and tell the user the bucket is low and when it resets; under 5%, stop and report the reset time instead of starting another run. A 5h window refills within five hours, a weekly one in days, so a low 5-hour bucket usually just means waiting.

If a run ends with status: ERROR whose text mentions quota, exhausted, rate limit or 429, treat it as a quota failure: run the check, report the reset time, and do not loop retries. The tree may be half-edited, so inspect it first. (No exhausted-quota error text was available when this was written, so match on meaning, not on an exact string.)

Second opinion (read-only agy review of the diff)

A separate agy run can check the worker's change without being able to touch anything: deny rules block every file write and shell command even under --dangerously-skip-permissions (verified: write_file covers edit_file too).

cd /abs/path/to/repo-or-worktree && git diff HEAD > /abs/tmp/review.diff && agy -p "You are a senior reviewer. Read /abs/tmp/review.diff and review it, reading other files in the repo for context if needed. You cannot and must not edit files or run commands. Answer in at most 15 lines: Critical issues (file:line), Suggestions, Verdict." <model-flags> --dangerously-skip-permissions --settings '{"permissions":{"deny":["command(*)","write_file(*)"]}}' --output-format json --print-timeout 300s

Untracked files are not in git diff HEAD; add them to the diff file yourself if they matter. These two rules are the ones that were tested; run git status afterwards anyway. This is a second model run, not proof: you still verify with tests. For a more independent view the user can name a different model for this run; otherwise it uses the configured <model-flags>.

If it goes wrong

  • Stopping a background Claude Code task (or its timeout) killed agy and its child processes in a test on Windows (verified), so nothing is normally left running. If you still suspect a stray process, look (tasklist | findstr /i agy on Windows, pgrep -a agy elsewhere), tell the user, and stop it only with their OK.
  • Quota or rate-limit errors: report them; do not loop retries.

Always verify yourself

After every run, regardless of status or hooks (other harnesses do not run them):

  1. git status and git diff in the repo or worktree: did it touch only the allowed files?
  2. Run the project's tests/linters yourself.
  3. Tell the user what the agent claimed (its short report) versus what you verified.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.