Google Agent Skills (Antigravity CLI, ex-Gemini CLI)

Why you'd careThe problem it solves

You find a clean tutorial for skills in Gemini CLI. The doc it links to is live, its text carries no deprecation notice (only a site-wide banner above it mentions the switch), and describes a discovery model that is genuinely well thought out — four tiers, a workspace directory, and a vendor-neutral path other tools could adopt. You install, sign in with the Google account on your AI Pro subscription, and the agent will not serve you. Nothing in the skills documentation itself warned you, because the skills documentation is not what changed. The client underneath it was withdrawn for individual accounts. The format is fine. The instructions are fine. The thing that reads them is the part that moved, and that is the failure mode worth internalising for every vendor on this list.

ConceptWhat it is

A Google Agent Skill is the same directory as everyone else's: a folder containing SKILL.md, with YAML frontmatter carrying a name and a description, then Markdown instructions and whatever reference files and scripts the instructions point at. Google added no format of its own.

What Google contributed was a discovery model. Its CLI documents four tiers rather than two, so a skill can arrive from the tool itself, from an installed extension, from your home directory, or from the checkout you are standing in — with the more specific tier winning on a name clash. And it pushed ~/.agents/skills/, a path with no vendor in it, as a place any harness could agree to look. That is the durable idea here, more than anything Google shipped around it.

The boundary to hold clearly: a skill format and a client that runs it are separate things with separate lifecycles. As of 2026-07-25, Gemini CLI is no longer served to free, AI Pro or AI Ultra sign-ins — that is a primary-sourced finding, not a rumour, and it reverses an earlier draft of this entry that called it unverified. Google's successor tooling is the Antigravity line. Whether Antigravity's CLI discovers the same four tiers, under the same paths, using the same frontmatter, is not established here. Do not assume continuity, and do not assume its absence either — check before you build on it.

How it worksThe mechanics

Gemini CLI's skills documentation — still live and unchanged in the google-gemini/gemini-cli repo, and served on geminicli.com beneath a site-wide banner that now reads “Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026” — describes discovery in four tiers, lowest precedence first:

# 1  built-in skills shipped inside the CLI

# 2  skills contributed by an installed extension

# 3  user skills
     ~/.gemini/skills/<skill-name>/SKILL.md
     ~/.agents/skills/<skill-name>/SKILL.md

# 4  workspace skills
     .gemini/skills/<skill-name>/SKILL.md
     .agents/skills/<skill-name>/SKILL.md

Later tiers override earlier ones on a name collision, so a workspace skill named deploy shadows a personal one, which shadows an extension's. That layering matters more than it looks: it is the mechanism by which a repo can pin a procedure for everyone who opens it, without touching anyone's home directory.

The frontmatter is the familiar pair. Name and description are what get injected at session start; the body is read only after the model matches the description to what you asked for.

---
name: bq-cost-guard
description: Reviews a BigQuery SQL statement for full-table scans and
  missing partition filters before it is run. Use when the user asks to
  run, review or estimate the cost of a BigQuery query.
---

Two practical consequences. First, if you write the same folder into both ~/.gemini/skills/ and ~/.agents/skills/, you have two skills with the same name and a precedence question you did not intend to ask — pick one location and symlink the other if you need both.

Second, the neutral path only helps where a harness has agreed to read it. Claude Code documents ~/.claude/skills/ and .claude/skills/; it is not documented to read ~/.agents/skills/, so moving a folder there does not make it universal. A vendor-neutral convention is a proposal until each client implements it: Codex, Cursor, GitHub Copilot and Antigravity now document reading .agents/skills, and Claude Code still does not.

At a glanceSee it

Gemini CLI merges four skill tiers, then the account tier decides whether anything runs at all.

Where it runsSurfaces and availability

The framing holds but the risk was overstated: the client wobbled and then landed. Antigravity CLI carried the skills format forward, paid API-key and enterprise auth still reaches Gemini CLI, and the same .agents/skills directory now serves Codex, Antigravity and Google's own hosted agents. So the lesson is narrower than "weight the durability of the harness above the elegance of the format": what broke was an authentication tier, not a file layout. Before concluding a CLI is gone, check which sign-in your account actually holds.

ExampleIn the real world

Arun writes bq-cost-guard: a folder with SKILL.md, a reference file listing the partitioned tables in the warehouse, and a script that runs a dry-run cost estimate. He puts it in ~/.agents/skills/ deliberately, because he read that the path is vendor-neutral and wants one copy for the whole team.

On his machine, nothing picks it up. Gemini CLI will not authenticate his AI Pro account. He copies the folder to .claude/skills/bq-cost-guard/ in the repo and it loads on the next session — the frontmatter parses, the description appears in the menu, and asking "is this query going to be expensive" matches it on the first try.

One line does need editing. Step 1 said to use the CLI's built-in web fetch to pull the current pricing page. That built-in is a Gemini CLI tool name, and it is not present. He rewrites it as fetch the current BigQuery on-demand price per TB and cite the URL you used, which any harness with a fetch capability can satisfy.

The reference file and the script travel untouched. What broke was one sentence naming one vendor's tool, and the client he originally wrote it for.

Not thisWhat it is often confused with

• Not a Google-specific formatsame SKILL.md, same required frontmatter pair. What Google added was the four-tier discovery order and the neutral directory name, not a schema.
• Not an extensiona Gemini CLI extension is packaging that can contribute skills alongside MCP servers and commands. The extension is the delivery vehicle; the skill is one thing it may carry.
• Not GEMINI.mdthat file is always-on project context, the same role CLAUDE.md and AGENTS.md play. A skill is conditional, named, and can bundle executables.
• Not a working clienta live documentation page describes a format, not an entitlement. On 2026-07-25 the doc was current and the CLI was not available to individual plans.
• Not universal because the path has no vendor in it~/.agents/skills/ is a proposal each harness must implement. Verify your harness reads it before treating it as the canonical copy.

LimitsWhen not to reach for it

• You are starting a new terminal-agent workflow.Do not build it on Gemini CLI without first confirming your auth path is still served; check that before writing a single skill.
• You want one canonical location.Do not make ~/.agents/skills/ your only copy and assume other tools find it. Symlink or copy into the path each harness documents.
• You need standing project context, not a procedure.A context file — GEMINI.md, AGENTS.md — costs less and always applies.
• The steps name a built-in tool.If the folder is meant to be portable, describe the action, not the tool that performs it.
• You need a new capability.Reaching a system the agent cannot currently touch is an MCP server, whichever vendor's CLI you end up on.

RelatedGo deeper