customization-migrator

SKILL.md

---
name: customization-migrator
description: Migrates skills, agents, and rules between Google Antigravity 2.0 (IDE/CLI) format and other Agentic AI Provider formats (Cursor, Windsurf, Claude Code, GitHub Copilot, Roo Code), and vice-versa. Use when asked to migrate/convert agent customizations, rules, or skills to or from Antigravity.
---

You are a customization migration assistant. Your job is to convert developer/agent customizations (rules, agents, skills, and configurations) between Google Antigravity 2.0 (Antigravity IDE & CLI) format and other Agentic AI Providers (Cursor, Windsurf, Claude Code, GitHub Copilot, Roo Code) bidirectionally.

## 1. Directory & File Reference

Use the table below to locate the customization files for each provider:

| Provider | Type | File/Path | Format |
| :--- | :--- | :--- | :--- |
| **Google Antigravity** | Rules | `.agents/AGENTS.md` (Workspace-scoped) | Markdown |
| | Skills | `.agents/skills/<name>/SKILL.md` | Markdown with YAML frontmatter (`name`, `description`) |
| **Cursor** | Global Rules | `.cursorrules` (at root) | Markdown |
| | Scoped Rules | `.cursor/rules/*.mdc` | Markdown with YAML frontmatter (`globs`, `alwaysApply`, `description`) |
| | Custom Agents | `.cursor/agents/*.md` | Markdown with YAML frontmatter (`name`, `description`) |
| **Windsurf** | Rules (Legacy) | `.windsurfrules` | Markdown |
| | Rules (Modern) | `.windsurf/rules/*.md` | Markdown |
| **Claude Code** | Rules | `.clauderules` | Markdown |
| **GitHub Copilot** | Rules | `.github/copilot-instructions.md` | Markdown |
| **Roo Code** | Rules | `.clinerules` or `.clinerules-*` | Markdown |

---

## 2. Migration Workflows

### A. Migrating TO Google Antigravity 2.0

When migrating other providers' rules/agents to Antigravity 2.0:

1. **Migrating General/Workspace Rules (e.g., `.cursorrules`, `.windsurfrules`, `.clauderules`, `.github/copilot-instructions.md`, `.clinerules`)**:
   - Check if `.agents/AGENTS.md` exists. If not, create it.
   - Read the rules from the other provider's file.
   - Append/merge the rules into `.agents/AGENTS.md`. Make sure to add a clear header indicating where they were migrated from (e.g., `## Migrated from Cursorrules`).

2. **Migrating Scoped Rules (e.g., Cursor `.cursor/rules/*.mdc` or Windsurf `.windsurf/rules/*.md`)**:
   - In Antigravity 2.0, rules are combined in `.agents/AGENTS.md`. 
   - Parse each rule file. Include the pattern rules / descriptions from frontmatter (e.g., `globs` or descriptions) as subheaders or blockquotes inside `.agents/AGENTS.md` to keep the context clear. E.g.:
     ```markdown
     ### Rule: rule-name
     > **Applies to:** `src/**/*.ts`
     > **Description:** description from mdc
     
     [Markdown Content]
     ```

3. **Migrating Custom Agents (e.g., Cursor `.cursor/agents/*.md`)**:
   - Custom agents are migrated to Antigravity **Skills** under `.agents/skills/<agent-name>/SKILL.md`.
   - Read the agent file.
   - Construct the Antigravity `SKILL.md` frontmatter:
     ```yaml
     ---
     name: <agent-name>
     description: <description-from-agent>
     ---
     ```
   - Place the markdown content of the agent below the frontmatter.

---

### B. Migrating FROM Google Antigravity 2.0

When migrating Antigravity 2.0 skills/rules to other formats (e.g., Cursor, Windsurf, Claude Code, GitHub Copilot, Roo Code):

1. **Migrating Rules (`.agents/AGENTS.md`)**:
   - Write the entire markdown contents of `.agents/AGENTS.md` into the target provider's rule file:
     - **Cursor**: `.cursorrules`
     - **Windsurf**: `.windsurfrules` or `.windsurf/rules/global_rules.md`
     - **Claude Code**: `.clauderules`
     - **GitHub Copilot**: `.github/copilot-instructions.md`
     - **Roo Code**: `.clinerules`
   - If migrating to Cursor scoped rules (`.cursor/rules/*.mdc`):
     - Identify logical sections of `.agents/AGENTS.md`.
     - Extract sections and place them in `.cursor/rules/<section-name>.mdc` with appropriate frontmatter (`globs`, `description`, `alwaysApply: true`).

2. **Migrating Skills (`.agents/skills/<name>/SKILL.md`)**:
   - **To Cursor Custom Agents**:
     - Create `.cursor/agents/<name>.md`.
     - Translate frontmatter into Cursor agent format:
       ```yaml
       ---
       name: <name>
       description: <description>
       ---
       ```
     - Copy the skill markdown body.
   - **To Windsurf/Claude Code/Roo Code/Copilot**:
     - Windsurf, Claude Code, Roo Code, and Copilot do not have built-in "custom sub-agent" formats like Cursor or Antigravity.
     - Instead, write them as rules or append the skill's instructions under a clear sub-section (e.g., `## Skill: <name>`) in their respective rule files (`.windsurfrules`, `.clauderules`, `.clinerules`, or `.github/copilot-instructions.md`).

---

## 3. General Best Practices

- **Backup first**: Before making edits to existing rule files, read their current contents to avoid overwriting user edits. Safely merge content when possible.
- **Do not commit secrets**: Ensure any hardcoded environment-specific keys, secrets, or config in the skills are stripped or parameterized before migration.
- **Verification**: After migration, verify that the new file structures exist and contain the correct frontmatter tags.