Home › Rules › Antigravity skills

Google Antigravity skills: where the folder goes, examples, and workflows vs skills

From Google's Antigravity docs, checked Nov 2, 2026. Sources below.

• Guide
• Antigravity
• Skills
• SKILL.md

Short answer: An Antigravity skill is a folder with a SKILL.md file inside. Put it in .agents/skills/<skill-name>/ in your project, or in ~/.gemini/config/skills/<skill-name>/ to use it in every project. SKILL.md starts with a short YAML header, and only description is required. The agent sees each skill's name and description on every turn, and reads the full file when your task matches. You can also run a skill yourself with /skill-name. Skills replace Antigravity's old workflows: Google's docs say the old workflows stopped working after October 19, 2026.

Where the Antigravity skills folder goes

For project skills, Antigravity checks the folder you open and each parent folder up to the repository root (the folder with .git). It doesn't look in subfolders below the folder you open. The older .agent/skills folder still works, but Google's docs say to use .agents/ for new projects.

One level deep only. Each skill folder must sit directly inside skills/. A skill at .agents/skills/database/migrate-schema/SKILL.md is skipped, because it's one level too deep. If you want nested folders, list them in a .agents/skills.json file. This one is based on Google's example:

{
  "entries": [
    {
      "path": ".agents/skills",
      "include_only": ["database/migrate-schema"]
    }
  ]
}

Want one skill in both the Antigravity app and the CLI? Google's docs say to put it in ~/.gemini/config/skills/.

What goes in a skill folder

Only SKILL.md is required. The other folders are optional. This is the layout from Google's docs:

my-skill/
├── SKILL.md       # Required: instructions and metadata
├── scripts/       # Optional: helper scripts
├── examples/      # Optional: reference examples
└── resources/     # Optional: templates, schemas, data files

If your skill has scripts, Google suggests telling the agent to run them with --help first, instead of reading all the code. That keeps the agent focused on your task.

The SKILL.md format

Every SKILL.md starts with a YAML header between two --- lines. Then come your instructions in plain Markdown. The header has two fields:

Google's tip: write the description in the third person and use the words people would actually type. For example, "Generates unit tests for Python code using pytest conventions."

How a skill gets used

1. The agent sees the list. On every turn, it sees each skill's name and description. Not the full file.
2. It picks one. If a skill looks like it fits your task, the agent reads the whole SKILL.md.
3. It follows the steps while it works on your task.

You don't have to ask for a skill. The agent decides from your message. If you want to be sure a skill is used, mention it by name, or type /skill-name in the message box. In the Antigravity CLI, each skill you add becomes a slash command too. If you add a skill while the CLI is running, run /skills reload or start a new chat.

Antigravity rereads your skills before each turn, so a new or edited skill works on your next message. To see what loaded: in the app or IDE, open Customizations; in the CLI, run /skills.

2 Antigravity skill examples you can copy

These two are our own examples for beginners, not from Google's docs. They use the format above. Change the commands to match your project.

Example 1: write tests

---
name: write-tests
description: Writes unit tests for new or changed code in this project and runs them. Use when the user asks for tests, adds a new function or page, or fixes a bug.
---

# Write tests

1. Find the test command in package.json (often npm test). Don't guess it.
2. Open one existing test file first and copy its style.
3. Write tests for the code that changed: the normal case,
   one edge case, and one error case.
4. Run the tests and show me the result.
5. If a test fails, tell me if the test or the code is wrong.
   Don't change the app code without asking me first.

Ask "add tests for the signup form" and the description should match. Or type /write-tests.

Example 2: database migration check

---
name: migration-check
description: Checks a database migration before it runs. Use when creating, editing or running a database migration, or when the user changes the database schema.
---

# Migration check

Before any migration runs:
1. Show me the migration file and explain in plain English what it changes.
2. Flag anything that deletes data: dropped tables, dropped columns,
   or DELETE statements.
3. Check that there is a way to undo it (a down migration or a backup step).
4. Run it on the local or test database first. Never on production.
5. Stop and wait for me to say "go" before running it anywhere else.

This one is a good fit for a skill because it's a job with several steps. Google's own example of a skill is "how to run database migrations."

Want more? Antigravity uses the open Agent Skills format, so our SKILL.md examples are a good place to start. Check any extra header fields against Google's docs, since Antigravity only lists name and description.

Antigravity workflows vs skills

Workflows were Antigravity's older way to save a list of steps. Google's docs say current workflows stop working on October 19, 2026, and that after that date, old workflow folders aren't read or run as slash commands. Google says instructions for a new workflows system will follow. For now, the docs point you to skills.

Turn your workflows into skills

Open the Antigravity app and type /migrate-workflows. The agent then:

• looks in .agents/workflows/ and ~/.gemini/config/workflows/,
• makes a .agents/skills/<workflow-name>/SKILL.md for each one,
• renames each old file with .bak on the end (deploy.md becomes deploy.md.bak),
• and turns the new skills on right away, for slash commands and for the agent to use on its own.

To do it by hand: make the folder (mkdir -p .agents/skills/deploy-staging), move the workflow file into it as SKILL.md, and make sure the header has a name and a clear description. Then test it with /deploy-staging. If a skill and a workflow have the same name, the skill wins.

Antigravity rules vs skills

Google's docs put it simply. Write a rule for things that must always be true, like "Always use zod for validation." Write a skill for a job with several steps, like "how to run database migrations."

They also load differently. Antigravity loads every rule it finds, and rules add up. Skills don't stack: if two skills have the same name, Antigravity keeps one. Your project's skill beats one in ~/.gemini/config/, and that beats a built-in skill. In the CLI, skills in ~/.gemini/antigravity-cli/skills/ and ~/.gemini/skills/ come first. Skills from a plugin are named plugin:skill, so they don't clash with yours. For rules, triggers and examples, see our Google Antigravity rules guide.

Coming from Gemini CLI?

Project skills moved. Gemini CLI used .gemini/skills/, and Antigravity CLI uses .agents/skills/. Google's migration guide says you must rename or move that folder yourself. Global skills in ~/.gemini/skills/ still work in Antigravity CLI. More on that move: GEMINI.md examples.

The Antigravity CLI can also install skill bundles packed as plugins, with agy plugin install and a plugin name, a GitHub URL or a local folder. agy plugin list shows what's installed.

Skill not loading? Check these

• File name. It must be SKILL.md, inside its own folder.
• Location. The folder is in .agents/skills/ in the folder you opened or a parent folder up to the repo root, or in ~/.gemini/config/skills/.
• Depth. The skill folder sits right inside skills/, not one level deeper. Or a skills.json lists it.
• Header. SKILL.md starts with the --- YAML block, with a description.
• Name clash. Another skill with the same name may be winning (see the order above).
• The agent never picks it. Make the description say clearly what the skill does and when to use it. Or call it with /skill-name.
• Old Gemini CLI folder. Skills in .gemini/skills/ need to move to .agents/skills/.

Related

• Google Antigravity rules (8 examples, triggers, where the files go)
• SKILL.md examples (7 copy-paste skills)
• Cursor rules vs skills
• GEMINI.md examples (Gemini CLI and Antigravity)
• Custom slash commands
• Every rules file format
• Free rules file generator

Sources

• Google Antigravity docs: Agent skills
• Google Antigravity docs: Customization discovery
• Google Antigravity docs: Migrate from workflows to skills
• Google Antigravity docs: Workflows
• Google Antigravity docs: Rules
• Google Antigravity docs: Migrating from Gemini CLI

Everything here was checked Nov 2, 2026 against Google's Antigravity docs. Antigravity changes often, and Google says a new workflows system is coming. If something here no longer matches, tell us at [email protected].