Key takeaways

  • A skill is a folder with a SKILL.md file; the description in its frontmatter is required and tells the agent when to use it.
  • Per Google's docs, project skills go in .agents/skills/ and global skills in ~/.gemini/config/skills/.
  • In the Antigravity CLI, run /skills reload after adding a skill mid-session, or start a new conversation.

To add a skill in Google Antigravity, create a folder with a SKILL.md file inside it and put that folder in .agents/skills/ in your project, or in ~/.gemini/config/skills/ to use it in every project. Google's Agent skills documentation says the agent reads the file's description to decide when to use the skill. There is nothing to install and no command to run.

This guide covers where skills go, what goes in SKILL.md, how each Antigravity product finds them, and the path mismatches that trip people up. Everything here comes from Google's Antigravity docs and its Google Developers codelab. For what Antigravity costs, see our guide to Google Antigravity pricing and plans.

What a skill is

A skill is a folder with a SKILL.md file. The file holds instructions the agent follows for one kind of task: a code-review checklist, a commit message format, a deploy routine. Google calls skills an open standard for extending the agent. A skill can also carry scripts and data files the agent can run or read.

The agent doesn't load every skill into every conversation. The docs describe three steps:

  1. Discovery: on every turn, the agent sees only the name and description of each available skill.
  2. Activation: if a skill looks relevant, the agent reads the full SKILL.md.
  3. Execution: the agent follows the instructions for your task.

That keeps the context window small, because a skill costs almost nothing until it is needed.

Where to put a skill

There are two scopes. Pick one.

Scope Path Who gets it
Workspace <workspace-root>/.agents/skills/<skill-folder>/ That project only
Global ~/.gemini/config/skills/<skill-folder>/ Every project on the machine

Google's docs add these details:

  • Commit workspace skills to version control and the whole team gets them. The agent also reads .agents/skills/ in each parent folder up to the repository root.
  • .agents/skills is the default. The older .agent/skills folder still works for backward compatibility.
  • Antigravity CLI only: ~/.gemini/config/plugins/<plugin-folder>/skills/ for plugin-provided skills, plus ~/.gemini/antigravity-cli/skills/ and ~/.gemini/skills/.
  • Antigravity IDE only: the legacy global path ~/.gemini/antigravity/skills/ is still supported.

How to add a skill, step by step

  1. Create the folder. In your project root, make .agents/skills/code-review/ (any lowercase, hyphenated name works).
  2. Create SKILL.md inside it, starting with YAML frontmatter, then your instructions in Markdown.
  3. Add optional subfolders only if you need them.
  4. Start a new conversation, or in the CLI run /skills reload, so the agent picks up the new skill.
  5. Check that it loaded. The codelab suggests asking "What skills are available?" in Antigravity, or running /skills in the CLI.

A skill folder looks like this:

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

The codelab uses references/ and assets/ for the supporting folders instead of examples/ and resources/. The two pages don't conflict, because SKILL.md is the only required file and the agent reads whatever relative paths you give it.

What goes in SKILL.md

The file starts with frontmatter. Two fields matter:

  • description is required. It says what the skill does and when to use it. The agent reads it to decide whether to apply the skill, so Google recommends writing it in the third person and including keywords. The codelab says a vague description such as "Database tools" is not enough.
  • name is optional. Use lowercase with hyphens. If you leave it out, the folder name is used.

A minimal skill, based on the git-commit skill in Google's codelab:

---
name: git-commit-formatter
description: Formats git commit messages according to the Conventional Commits specification. Use when committing changes or writing commit messages.
---

Goal: write every commit message in Conventional Commits format.

Instructions:
1. Start with a type such as feat, fix or docs.
2. Keep the summary line short.
3. Explain the reason for the change in the body.

The Markdown body is what gets loaded into context when the skill activates. The codelab says it typically holds a goal, step-by-step instructions, few-shot examples and constraints. Its database skill, for example, states that only SELECT statements are allowed.

How to use a skill once it is added

You don't have to name a skill. The agent picks it when your request matches the description. You can still ask for one by name to make sure it is used. How you invoke it depends on the product:

  • Antigravity App: the agent invokes skills automatically, or you type /<skill-name> in the message box.
  • Antigravity CLI: each skill becomes a slash command, so a skill named deploy-staging gives you /deploy-staging.
  • Antigravity IDE: active skills show in the Customizations menu in the agent side panel.

The CLI can also package skills in plugins, managed with agy plugin list and agy plugin install <plugin-name>, from a name, a GitHub URL or a local path.

Copy Google's example skills

The codelab includes a repository of example skills at github.com/rominirani/antigravity-skills. Clone it, open skills_tutorial, and copy any of the four folders (git-commit-formatter, license-header-adder, database-schema-validator, json-to-pydantic) into <project-root>/.agents/skills/ or the global folder. They show four patterns: instructions only, a reference file read on demand, few-shot examples, and a script the agent runs and judges by exit code.

Common problems

  • The skill doesn't show up. Check the folder is directly under .agents/skills/ and contains a file named exactly SKILL.md. In the CLI, run /skills reload or start a new conversation.
  • The skill never triggers. The description is probably too vague. Rewrite it with the task and the words you would use when asking for it.
  • The global path differs between pages. The skills docs and the codelab give ~/.gemini/config/skills/ for global skills, but the codelab also gives ~/.gemini/antigravity-cli/skills/ for the CLI and does not reconcile the two. If a global skill doesn't load in the CLI, put it in the CLI folder, or use the workspace path, which is the same everywhere.
  • Skills installed with other tools. The codelab says skills installed with npx skills land in ~/.agents/skills, which Antigravity picks up but the CLI does not. Copy them into a project or global skills folder for the CLI. Agents CLI skills install to the same place, and the codelab says to move them to ~/.gemini/antigravity-cli/skills for the CLI.

Tips from Google's docs

  • Keep each skill focused on one task.
  • Write specific descriptions, because they decide whether the agent uses the skill.
  • Tell the agent to run scripts with --help first instead of reading their full source, to keep context focused.
  • For a complex skill, include a decision tree for choosing an approach.

Skills are one of several ways to steer the agent. For the newer agent features, see our report on Antigravity remote agents and voice mode.

Frequently asked questions

Where do Antigravity skills go?

Project skills go in .agents/skills/<skill-folder>/ at the workspace root, and global skills go in ~/.gemini/config/skills/<skill-folder>/. The older .agent/skills folder still works.

What is a SKILL.md file in Antigravity?

It is the required file in a skill folder. It starts with YAML frontmatter (a required description and an optional name) followed by Markdown instructions the agent follows when it activates the skill.

How do I use a skill in Antigravity?

The agent applies a skill on its own when your request matches its description. In the app you can also type /<skill-name>, and in the CLI each skill is a slash command of the same name.

Why isn't my Antigravity skill showing up?

Check that the folder sits directly under a skills folder and holds a file named SKILL.md. In the CLI, run /skills reload or start a new conversation, then run /skills to list what loaded.

Sources

  1. Agent skillsGoogle Antigravity
  2. Authoring Google Antigravity SkillsGoogle Developers

Add ClaudeGPT Si as a preferred source on Google