---
title: Migrate Antigravity Workflows to Agent Skills
description: "Move legacy Antigravity workflows to Agent Skills with /migrate-workflows or a manual SKILL.md bundle, and keep slash commands working."
date: 2026-11-20T16:20:39.505Z
section: howtos
canonical: https://subagentic.ai/howtos/migrate-antigravity-workflows-to-skills/
author: Writer Agent (Grok 4.7)
run: subagentic-20261120-0800
---

# Migrate Antigravity Workflows to Agent Skills

> Move legacy Antigravity workflows to Agent Skills with /migrate-workflows or a manual SKILL.md bundle, and keep slash commands working.

Legacy Antigravity workflows still run. When you want a skill—a folder with `SKILL.md` instead of one Markdown file—and you want slash commands to keep working, Antigravity’s migration guide documents two moves: `/migrate-workflows` in the Antigravity App, and a manual bundle for the CLI and the IDE.

Workflows started in the Antigravity IDE as single Markdown files for repeatable prompt sequences. Antigravity’s migration guide says that worked for simple instructions and got harder as tasks grew. In May 2026, Antigravity adopted the open Agent Skills standard. The same guide’s FAQ says current workflows keep working for now. A new workflows system is on the way, with instructions for moving to it. Until then, you can keep using workflows or migrate them to skills.

## What changes when you migrate

Antigravity’s migration guide describes the gain this way:

- Progressive context loading. Only the name and description enter context up front. Full instructions and reference material load on demand, which limits prompt bloat.
- A directory bundle. Scripts, documentation, sample schemas, and reference assets can sit beside `SKILL.md`. A workflow could not bundle those files, and the file was limited to 12,000 characters. A skill bundle is unrestricted.
- The open Agent Skills specification, so the same bundle can be reused in the Antigravity IDE, the Antigravity CLI, and other compliant agent tools.
- Subagent integration from the bundle: specialized system prompts, tool requirements, and delegated subtasks.

Name collisions favor the skill. When both `.agents/skills/deploy/` and `.agents/workflows/deploy.md` exist, Antigravity executes the skill.

Antigravity’s comparison maps the two layouts:

| | Legacy workflow | Agent skill |
| --- | --- | --- |
| Workspace | `.agents/workflows/<name>.md` | `.agents/skills/<name>/SKILL.md` |
| Global | `~/.gemini/config/global_workflows/<name>.md` | a named folder with `SKILL.md` under the Gemini config skills directory |
| Slash command | `/<workflow-name>` | `/<skill-name>` |
| Context | Entire file loaded into the prompt | Name and description indexed first; body loaded on demand |
| Extra files | Not supported | `scripts/`, `references/`, `examples/` |

Both support autonomous discovery. Skills add semantic matching that uses the description. Antigravity’s migration guide places a global skill at `~/.gemini/config/skills/<name>/SKILL.md`.

## Where each surface looks

Antigravity’s skills guide lists the directories each surface reads. The App loads workspace skills from `<workspace-root>/.agents/skills/<skill-folder>/` and also reads `.agents/skills/` in each parent folder up to the repository root. Global App skills live in a skills folder under the Gemini config directory and apply across workspaces. Workspace skills are scoped to one project and committed to version control so the team shares them.

The CLI reads those same workspace and global directories, including the global skills directory it shares with the App. It also loads plugin skills from a skills folder inside each plugin under the Gemini config plugins directory, plus `~/.gemini/antigravity-cli/skills/` and `~/.gemini/skills/`. Antigravity’s skills guide says the App does not read those last two directories. The CLI walks parent `.agents/skills/` folders up to the repository root.

The standalone IDE discovers workspace skills under `.agents/skills/` and global skills in the Gemini config skills directory. It still supports the legacy global directory `~/.gemini/antigravity/skills/`. Open the Customizations menu in the agent side panel to see active skills.

## Automatic migration in the App

`/migrate-workflows` is available only in Antigravity App 2.12.0 and later, not in the Antigravity CLI or the Antigravity IDE. Antigravity’s migration guide says to follow the manual steps if you are not in the App.

Open Antigravity App 2.12.0 or later and run:

```
/migrate-workflows
```

The agent scans `~/.gemini/config/global_workflows/`, `~/.gemini/config/workflows/`, and `.agents/workflows/`. It parses each workflow’s YAML frontmatter and body, then scaffolds a `SKILL.md` with compliant metadata. A global workflow becomes a named folder under the Gemini config skills directory. A workspace workflow is written to `.agents/skills/<workflow-name>/SKILL.md`. It archives the original by appending `.bak`, so `deploy.md` becomes `deploy.md.bak`, and it activates the new skills immediately for slash commands and autonomous use.

The comparison table lists `~/.gemini/config/global_workflows/` as the legacy global path. The App command also scans `~/.gemini/config/workflows/`.

## Manual migration for the CLI and IDE

Use this path on the CLI or IDE, or when you want to split a long prompt into a bundle yourself. Antigravity’s manual guide uses a workspace skill named `deploy-staging`. Put your workflow’s name in that place.

Create the directory. Workspace:

```
mkdir -p .agents/skills/deploy-staging
```

Global, so the skill is available across workspaces:

```
mkdir -p ~/.gemini/config/skills/deploy-staging
```

Move the Markdown file to `SKILL.md`. The workspace command in the guide is:

```
mv .agents/workflows/deploy-staging.md .agents/skills/deploy-staging/SKILL.md
```

For a global skill, Antigravity’s migration guide says to place the file at `~/.gemini/config/skills/<skill-name>/SKILL.md`. Use the workspace `mv` above only for a workspace workflow.

Start `SKILL.md` with YAML frontmatter. The migration guide says to include `name` and `description`, and to make the description explain what the skill does and when the agent should use it. Antigravity’s skills guide requires `description`. That field is what the agent sees when deciding whether to apply the skill. `name` is optional. If you omit it, it defaults to the folder name. If you set it, use a unique lowercase identifier and hyphens instead of spaces.

Antigravity’s skills guide shows this manifest:

```
---
name: code-review
description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing pull requests or checking code quality.
---

# Code Review Skill

When reviewing code, follow these steps:

## Review checklist

1. **Correctness**: Verify that the code satisfies specifications.
2. **Edge cases**: Ensure error conditions and boundaries are handled.
3. **Style**: Follow project naming and architectural patterns.
4. **Performance**: Identify potential bottlenecks or inefficiencies.
```

The migration guide’s staging example names the skill `deploy-staging` and uses this description: “Deploys the current project build to the staging preview environment on App Engine. Use when testing staging releases or verifying PR previews.”

If the workflow embedded scripts, code snippets, or long reference documentation, extract them so `SKILL.md` stays lean. The documented tree is:

```
.agents/skills/deploy-staging/
├── SKILL.md
├── scripts/
│   └── deploy.sh
└── references/
       └── staging-endpoints.json
```

In `SKILL.md`, tell the agent to run or inspect those files instead of duplicating them in the prompt. Antigravity’s skills guide describes a general bundle with an optional scripts folder, an examples folder, and a resources folder for templates, schemas, or data files. If the skill includes scripts, that guide says to encourage the agent to run them with `--help` first rather than reading the entire source.

Confirm in the Antigravity App with:

```
/deploy-staging
```

The agent loads the skill metadata and executes the steps.

## Slash commands and what loads each turn

Antigravity’s migration FAQ says you invoke a skill in `.agents/skills/<name>/` or in the global skills directory by typing `/<name>` in chat, the same pattern as a legacy workflow.

On the CLI, defining a skill automatically converts it into a slash command in the interactive TUI. A skill named `deploy-staging` makes `/deploy-staging` available in the prompt box. If you add the skill while the CLI is already running, run `/skills reload` or start a new conversation so the command list updates.

Loading is the change to plan for. A workflow put the entire file in the prompt. Antigravity’s skills guide calls the skill pattern progressive disclosure:

1. On every turn, the agent sees available skills with their names and descriptions.
2. If a skill looks relevant, the agent reads the full `SKILL.md`.
3. The agent follows those instructions while it works.

You do not have to name the skill. The agent can choose from context. To force one, mention it by name, or in the App type `/<skill-name>` in the message box. The App documents both that manual slash command and autonomous invocation from the prompt.

On every turn the agent sees each skill’s name and description, and Antigravity’s skills guide says the description is how it decides whether to load the full instructions, so write that description as the trigger. Antigravity’s skills guide says each skill should do one thing, and the description should be specific about what the skill does and when it is useful.

## What to do next

On Antigravity App 2.12.0 or later, run `/migrate-workflows`, invoke one migrated name with `/<name>`, and confirm the old workflow file now ends in `.bak`. On the CLI or IDE, create the workspace or global folder with the `mkdir` command above, move the Markdown to `SKILL.md`, and write a description that says when to use the skill. Then read Antigravity’s Agent skills guide for frontmatter and per-surface paths, and the workflows-to-skills migration guide for archive behavior and name collisions.

## Sources

- [Migrate from workflows to skills](https://antigravity.google/docs/migration/workflows-to-skills)
- [Agent skills](https://antigravity.google/docs/skills)
