How to Create a Skill for Antigravity (First Skill Guide)

To create a skill for Antigravity, make a folder, put a SKILL.md file inside it, and give that file a clear description plus step-by-step instructions. Save the folder in .agents/skills/ in your workspace (or in a global skills folder), and the agent will pick it up when a task matches.

What a skill is

According to the official Antigravity skills documentation, a skill is a folder containing a SKILL.md file with instructions that the agent can follow when working on specific tasks. It is an open standard, so the same folder layout is not tied to one product. For background, read what agent skills are.

The key difference from Antigravity rules is timing. Rules are always on. A skill is on demand: the agent only reads it when the task calls for it, so a long, detailed skill does not clutter every conversation.

Folder structure

Only SKILL.md is required. The other folders are optional:

my-skill/
├── SKILL.md      # required: frontmatter + instructions
├── scripts/      # optional: helper scripts
├── examples/     # optional: reference implementations
└── resources/    # optional: templates, schemas, data files

Start with just the SKILL.md.

A complete minimal SKILL.md

This is our own example: a skill that writes commit messages. It is deliberately small.

---
name: commit-message
description: Writes a clear commit message from staged changes. Use when the user asks for a commit message or is about to commit.
---

# Commit message

## Steps
1. Look at the staged diff, not the whole working tree.
2. Write a subject line of 50 characters or fewer, in the imperative
   mood ("Add retry to upload", not "Added retry").
3. Leave one blank line, then a short body that explains why the change
   was made, not what each line does.
4. If the diff mixes unrelated changes, say so and suggest splitting
   the commit instead of writing one vague message.

## Do not
- Do not invent ticket numbers.
- Do not mention files that are not in the diff.

The file has two parts: frontmatter between the --- lines, and the instructions below it in plain Markdown.

The documented frontmatter has two fields. name is optional: use lowercase letters and hyphens, and if you leave it out it defaults to the folder name. description is required and should say what the skill does and when to use it.

Where to put it

Pick a workspace location for a skill that belongs to one project, or a global location for one you want everywhere.

| Scope | Location |

|---|---|

| Workspace (App, CLI, IDE) | /.agents/skills// |

| Global, App and IDE | ~/.gemini/config/skills// |

| Global, CLI | ~/.gemini/antigravity-cli/skills// |

| CLI plugin skills | ~/.gemini/antigravity-cli/plugins//skills/ |

The IDE also supports the legacy ~/.gemini/antigravity/skills/ path, and the older .agent/skills folder still works for backward compatibility. For new skills, use .agents/skills. Our guide on how to install skills in Antigravity covers copying someone else's skill into these folders.

For our example, the workspace path would be .agents/skills/commit-message/SKILL.md.

How to check that it loaded

Antigravity uses progressive disclosure. At the start of a conversation the agent sees only each skill's name and description. If a skill looks relevant to your request, the agent reads the full SKILL.md and follows it.

To confirm your skill is there:

IDE: open the Customizations menu in the agent side panel, which lists active skills.

App: type / in the prompt panel to invoke it, for example /commit-message.

CLI: the / slash command appears in the interactive TUI.

You can also mention the skill by name in your prompt to make sure the agent uses it.

How to write a good description

The description is what the agent matches on, so it matters more than anything else in the file. Since the agent sees only the name and description up front, a vague description means the skill never gets opened.

The official docs give a sample: "Generates unit tests for Python code using pytest conventions." Notice the pattern: a verb, the specific thing it works on, and the convention it follows. Add a "when" clause so the agent knows the trigger.

Weak: "Helps with git."

Better: "Writes a clear commit message from staged changes. Use when the user asks for a commit message or is about to commit."

Use the words a person would actually type. If you would say "changelog" and "release notes", put both in the description. Keep one skill to one job.

When to add scripts, examples and resources

Plain instructions are enough for many skills. Add folders when the agent needs more than words:

scripts/ for work that should be done the same way each time, such as a linter wrapper or a file converter. The docs advise running scripts with --help first, so make sure yours prints useful usage text.

examples/ for reference implementations. One finished sample often teaches the agent more than a paragraph of description.

resources/ for templates, schemas and data files the instructions point to, such as a changelog template.

Refer to these files by relative path in your SKILL.md, so the agent knows they exist and when to open them. For a real-world example of a skill with supporting files, see our review of the UI UX Pro Max skill.

Test it with a real prompt

Write the skill, then try to break it.

1. Stage a small change in a test repository.

2. Ask in plain words, without naming the skill: "Write me a commit message for this."

3. Check whether the agent used your steps: subject length, imperative mood, a body about why.

4. Ask again, this time naming the skill, and compare.

If the skill only works when you name it, the description is the problem. If it triggers but the output ignores a step, the instructions are too vague or too long. Change one thing at a time.

Common mistakes

A vague description. "Useful coding helper" tells the agent nothing about when to load it.

Writing it like a README. The agent needs actions and constraints, not a project history.

Too many jobs in one skill. Split it. Smaller skills are matched more accurately.

Wrong folder. The folder must sit directly inside a skills directory, with SKILL.md at its top level. A nested extra folder can hide it.

Skipping the "do not" list. Short limits, such as "do not invent ticket numbers", prevent the most common bad outputs.

Treating other people's skills as safe. Read any skill before you install it. See our review method for what we check.

FAQ

Do I need frontmatter in SKILL.md?

You need a description, and it goes in the frontmatter. The name field is optional and defaults to the folder name.

What is the difference between a skill and a rule?

A rule is always on. A skill is loaded only when the agent decides it is relevant to the task, or when you invoke it by name.

Can I use the same skill in the App, CLI and IDE?

Workspace skills in .agents/skills/ work across the App, CLI and IDE. Global skills live in different folders depending on the product, so copy the folder to each location you use.

Why does my skill not show up?

Check the folder path first, then confirm SKILL.md is directly inside the skill folder and the frontmatter is closed with a second --- line. Then look in the Customizations menu (IDE) or for the slash command (App, CLI).

Can a skill run code?

A skill can include a scripts/ folder with helper scripts that its instructions tell the agent to use. The agent still works in your environment, so review scripts the way you would review any code.