|
| 1 | +# Antigravity Setup and Usage Guide |
| 2 | + |
| 3 | +Google's [Antigravity](https://antigravity.dev) is an AI coding IDE that uses a `.agent/` directory convention for configuration. ECC provides first-class support for Antigravity through its selective install system. |
| 4 | + |
| 5 | +## Quick Start |
| 6 | + |
| 7 | +```bash |
| 8 | +# Install ECC with Antigravity target |
| 9 | +./install.sh --target antigravity typescript |
| 10 | + |
| 11 | +# Or with multiple language modules |
| 12 | +./install.sh --target antigravity typescript python go |
| 13 | +``` |
| 14 | + |
| 15 | +This installs ECC components into your project's `.agent/` directory, ready for Antigravity to pick up. |
| 16 | + |
| 17 | +## How the Install Mapping Works |
| 18 | + |
| 19 | +ECC remaps its component structure to match Antigravity's expected layout: |
| 20 | + |
| 21 | +| ECC Source | Antigravity Destination | What It Contains | |
| 22 | +|------------|------------------------|------------------| |
| 23 | +| `rules/` | `.agent/rules/` | Language rules and coding standards (flattened) | |
| 24 | +| `commands/` | `.agent/workflows/` | Slash commands become Antigravity workflows | |
| 25 | +| `agents/` | `.agent/skills/` | Agent definitions become Antigravity skills | |
| 26 | + |
| 27 | +> **Note on `.agents/` vs `.agent/` vs `agents/`**: The installer only handles three source paths explicitly: `rules` → `.agent/rules/`, `commands` → `.agent/workflows/`, and `agents` (no dot prefix) → `.agent/skills/`. The dot-prefixed `.agents/` directory in the ECC repo is a **static layout** for Codex/Antigravity skill definitions and `openai.yaml` configs — it is not directly mapped by the installer. Any `.agents/` path falls through to the default scaffold operation. If you want `.agents/skills/` content available in the Antigravity runtime, you must manually copy it to `.agent/skills/`. |
| 28 | +
|
| 29 | +### Key Differences from Claude Code |
| 30 | + |
| 31 | +- **Rules are flattened**: Claude Code nests rules under subdirectories (`rules/common/`, `rules/typescript/`). Antigravity expects a flat `rules/` directory — the installer handles this automatically. |
| 32 | +- **Commands become workflows**: ECC's `/command` files land in `.agent/workflows/`, which is Antigravity's equivalent of slash commands. |
| 33 | +- **Agents become skills**: ECC agent definitions map to `.agent/skills/`, where Antigravity looks for skill configurations. |
| 34 | + |
| 35 | +## Directory Structure After Install |
| 36 | + |
| 37 | +``` |
| 38 | +your-project/ |
| 39 | +├── .agent/ |
| 40 | +│ ├── rules/ |
| 41 | +│ │ ├── coding-standards.md |
| 42 | +│ │ ├── testing.md |
| 43 | +│ │ ├── security.md |
| 44 | +│ │ └── typescript.md # language-specific rules |
| 45 | +│ ├── workflows/ |
| 46 | +│ │ ├── plan.md |
| 47 | +│ │ ├── code-review.md |
| 48 | +│ │ ├── tdd.md |
| 49 | +│ │ └── ... |
| 50 | +│ ├── skills/ |
| 51 | +│ │ ├── planner.md |
| 52 | +│ │ ├── code-reviewer.md |
| 53 | +│ │ ├── tdd-guide.md |
| 54 | +│ │ └── ... |
| 55 | +│ └── ecc-install-state.json # tracks what ECC installed |
| 56 | +``` |
| 57 | + |
| 58 | +## The `openai.yaml` Agent Config |
| 59 | + |
| 60 | +Each skill directory under `.agents/skills/` contains an `agents/openai.yaml` file at the path `.agents/skills/<skill-name>/agents/openai.yaml` that configures the skill for Antigravity: |
| 61 | + |
| 62 | +```yaml |
| 63 | +interface: |
| 64 | + display_name: "API Design" |
| 65 | + short_description: "REST API design patterns and best practices" |
| 66 | + brand_color: "#F97316" |
| 67 | + default_prompt: "Design REST API: resources, status codes, pagination" |
| 68 | +policy: |
| 69 | + allow_implicit_invocation: true |
| 70 | +``` |
| 71 | +
|
| 72 | +| Field | Purpose | |
| 73 | +|-------|---------| |
| 74 | +| `display_name` | Human-readable name shown in Antigravity's UI | |
| 75 | +| `short_description` | Brief description of what the skill does | |
| 76 | +| `brand_color` | Hex color for the skill's visual badge | |
| 77 | +| `default_prompt` | Suggested prompt when the skill is invoked manually | |
| 78 | +| `allow_implicit_invocation` | When `true`, Antigravity can activate the skill automatically based on context | |
| 79 | + |
| 80 | +## Managing Your Installation |
| 81 | + |
| 82 | +### Check What's Installed |
| 83 | + |
| 84 | +```bash |
| 85 | +node scripts/list-installed.js --target antigravity |
| 86 | +``` |
| 87 | + |
| 88 | +### Repair a Broken Install |
| 89 | + |
| 90 | +```bash |
| 91 | +# First, diagnose what's wrong |
| 92 | +node scripts/doctor.js --target antigravity |
| 93 | +
|
| 94 | +# Then, restore missing or drifted files |
| 95 | +node scripts/repair.js --target antigravity |
| 96 | +``` |
| 97 | + |
| 98 | +### Uninstall |
| 99 | + |
| 100 | +```bash |
| 101 | +node scripts/uninstall.js --target antigravity |
| 102 | +``` |
| 103 | + |
| 104 | +### Install State |
| 105 | + |
| 106 | +The installer writes `.agent/ecc-install-state.json` to track which files ECC owns. This enables safe uninstall and repair — ECC will never touch files it didn't create. |
| 107 | + |
| 108 | +## Adding Custom Skills for Antigravity |
| 109 | + |
| 110 | +If you're contributing a new skill and want it available on Antigravity: |
| 111 | + |
| 112 | +1. Create the skill under `skills/your-skill-name/SKILL.md` as usual |
| 113 | +2. Add an agent definition at `agents/your-skill-name.md` — this is the path the installer maps to `.agent/skills/` at runtime, making your skill available in the Antigravity harness |
| 114 | +3. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — this is a static repo layout consumed by Codex for implicit invocation metadata |
| 115 | +4. Mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this static copy is used by Codex and serves as a reference for Antigravity |
| 116 | +5. Mention in your PR that you added Antigravity support |
| 117 | + |
| 118 | +> **Key distinction**: The installer deploys `agents/` (no dot) → `.agent/skills/` — this is what makes skills available at runtime. The `.agents/` (dot-prefixed) directory is a separate static layout for Codex `openai.yaml` configs and is not auto-deployed by the installer. |
| 119 | + |
| 120 | +See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full contribution guide. |
| 121 | + |
| 122 | +## Comparison with Other Targets |
| 123 | + |
| 124 | +| Feature | Claude Code | Cursor | Codex | Antigravity | |
| 125 | +|---------|-------------|--------|-------|-------------| |
| 126 | +| Install target | `claude-home` | `cursor-project` | `codex-home` | `antigravity` | |
| 127 | +| Config root | `~/.claude/` | `.cursor/` | `~/.codex/` | `.agent/` | |
| 128 | +| Scope | User-level | Project-level | User-level | Project-level | |
| 129 | +| Rules format | Nested dirs | Flat | Flat | Flat | |
| 130 | +| Commands | `commands/` | N/A | N/A | `workflows/` | |
| 131 | +| Agents/Skills | `agents/` | N/A | N/A | `skills/` | |
| 132 | +| Install state | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | `ecc-install-state.json` | |
| 133 | + |
| 134 | +## Troubleshooting |
| 135 | + |
| 136 | +### Skills not loading in Antigravity |
| 137 | + |
| 138 | +- Verify the `.agent/` directory exists in your project root (not home directory) |
| 139 | +- Check that `ecc-install-state.json` was created — if missing, re-run the installer |
| 140 | +- Ensure files have `.md` extension and valid frontmatter |
| 141 | + |
| 142 | +### Rules not applying |
| 143 | + |
| 144 | +- Rules must be in `.agent/rules/`, not nested in subdirectories |
| 145 | +- Run `node scripts/doctor.js --target antigravity` to verify the install |
| 146 | + |
| 147 | +### Workflows not available |
| 148 | + |
| 149 | +- Antigravity looks for workflows in `.agent/workflows/`, not `commands/` |
| 150 | +- If you manually copied ECC commands, rename the directory |
| 151 | + |
| 152 | +## Related Resources |
| 153 | + |
| 154 | +- [Selective Install Architecture](./SELECTIVE-INSTALL-ARCHITECTURE.md) — how the install system works under the hood |
| 155 | +- [Selective Install Design](./SELECTIVE-INSTALL-DESIGN.md) — design decisions and target adapter contracts |
| 156 | +- [CONTRIBUTING.md](../CONTRIBUTING.md) — how to contribute skills, agents, and commands |
0 commit comments