Skip to content

Commit cfb3370

Browse files
docs: add Antigravity setup and usage guide (anomalyco#552)
* docs: add Antigravity setup and usage guide Addresses anomalyco#462 — users were confused about Antigravity skills setup. Adds a comprehensive guide covering: - Install mapping (ECC → .agent/ directory) - Directory structure after install - openai.yaml agent config format - Managing installs (list, doctor, uninstall) - Cross-target comparison table - Troubleshooting common issues - How to contribute skills with Antigravity support Also links the guide from the README FAQ section. * fix: address review feedback on Antigravity guide - Remove spurious skills/ row from install mapping table, add note clarifying .agents/skills/ is static repo layout not installer-mapped - Fix repair section: doctor.js diagnoses, repair.js restores - Fix .agents/ → .agent/ path typo in custom skills section - Clarify 3-step workflow for adding Antigravity skills - Fix antigravity-project → antigravity in comparison table - Fix "flatten" → "flattened" grammar in README - Clarify openai.yaml full nested path structure * fix: clarify .agents/ vs .agent/ naming and fix Cursor comparison - Explain that .agents/ (with 's') is ECC source, .agent/ (no 's') is Antigravity runtime — installer copies between them - Fix Cursor Agents/Skills column: Cursor has no explicit agents/skills mapping (only rules), changed from 'skills/' to 'N/A' * fix: correct installer behavior claims and command style - Fix .agents/ vs .agent/ note: clarify that only rules, commands, and agents (no dot) are explicitly mapped by the installer. The dot-prefixed .agents/ directory falls through to default scaffold, not a direct copy. - Fix contributor workflow: remove false auto-deploy claim for openai.yaml. Clarify .agents/ is static repo layout, not installer-deployed. - Fix uninstall command: use direct script call (node scripts/uninstall.js) for consistency with doctor.js, repair.js, list-installed.js. * fix: add missing agents/ step to contributor workflow Contributors must add an agent definition at agents/ (no dot) for the installer to deploy it to .agent/skills/ at runtime. Without this step, skills only exist in the static .agents/ layout and are never deployed. --------- Co-authored-by: vazidmansuri005 <[email protected]>
1 parent d697f2e commit cfb3370

2 files changed

Lines changed: 157 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -835,7 +835,7 @@ Yes. ECC is cross-platform:
835835
- **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support).
836836
- **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#-opencode-support).
837837
- **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257).
838-
- **Antigravity**: Tightly integrated setup for workflows, skills, and flatten rules in `.agent/`.
838+
- **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md).
839839
- **Claude Code**: Native — this is the primary target.
840840
</details>
841841

‎docs/ANTIGRAVITY-GUIDE.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
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

Comments
 (0)