subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

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.

google-antigravityagent-skillsworkflows

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