ECC/docs/ANTIGRAVITY-GUIDE.md

Antigravity Setup and Usage Guide

Google Antigravity 2.0 discovers workspace customizations from the project-local .agents/ directory. ECC's Antigravity target installs native rules, workflows, skills, and custom agents into that directory.

Quick start

# Install the minimal profile
./install.sh --profile minimal --target antigravity

# Compatibility syntax: common rules plus only these language packs
./install.sh --target antigravity typescript python go

Start a new Antigravity conversation after installing so the agent receives the updated skill inventory.

Native install mapping

ECC source	Antigravity destination	Purpose
rules/	.agents/rules/	Workspace rules, flattened with collision-safe names
commands/	.agents/workflows/	User-invoked slash workflows
skills/<name>/	.agents/skills/<name>/	Agent Skills with a required SKILL.md
agents/<name>.md	.agents/agents/<name>.md	Custom main agents and subagents

ECC does not copy the repository's .agents/ directory wholesale. That source tree is Codex packaging and contains Codex-specific marketplace metadata. An Antigravity plugin instead requires .agents/plugins/<plugin-name>/plugin.json.

Installed custom agent definitions are adapted to Antigravity's frontmatter: Claude model tiers become flash or pro, and Claude tool names become their Antigravity equivalents. Unsupported tool identifiers are never emitted because Antigravity warns that invalid tool names can hang custom-agent execution.

Expected project tree

your-project/
└── .agents/
    ├── rules/
    │   ├── common-coding-style.md
    │   └── typescript-testing.md
    ├── workflows/
    │   └── plan.md
    ├── skills/
    │   └── coding-standards/
    │       └── SKILL.md
    ├── agents/
    │   └── code-reviewer.md
    └── ecc-install-state.json

Verify the installation

node scripts/list-installed.js --target antigravity
node scripts/doctor.js --target antigravity
rg --files .agents/skills -g 'SKILL.md'
rg --files .agents/agents -g '*.md'

In Antigravity, open Settings > Customizations, confirm that workspace skills appear, start a new conversation, and request one by its exact name.

Existing .agent/ installations

Antigravity still reads legacy .agent/rules and .agent/skills, but ECC now uses the canonical .agents/ layout. Do not rename .agent manually because ECC install-state contains absolute managed paths.

Rerun the same ECC install command after updating. ECC writes and verifies the new .agents/ecc-install-state.json first, then removes only unchanged files owned by the valid legacy state. Modified and unmanaged files remain in .agent/ and remain discoverable by doctor and uninstall until handled.

Preview lifecycle operations before applying them when desired:

node scripts/doctor.js --target antigravity
node scripts/repair.js --target antigravity --dry-run
node scripts/uninstall.js --target antigravity --dry-run

Troubleshooting

Skills do not appear

• A valid skill must be .agents/skills/<name>/SKILL.md.
• .agent/.agents/skills is an obsolete nested layout from older ECC builds.
• Start a new conversation after changing skill files.

Rules do not apply

• Confirm the files are directly under .agents/rules/.
• Run doctor and inspect any missing or drifted managed-file warning.

Workflows do not appear

• Confirm the files are under .agents/workflows/.
• Invoke a workflow with /<workflow-name> after restarting Antigravity.

Official Antigravity references

• Skills
• Rules and workflows
• Custom agents and subagents
• Plugins

See CONTRIBUTING.md for ECC contribution guidance and SELECTIVE-INSTALL-ARCHITECTURE.md for the installer lifecycle contract.