docs: add Antigravity setup and usage guide#552
Open
vazidmansuri005 wants to merge 5 commits intoaffaan-m:mainfrom
Open
docs: add Antigravity setup and usage guide#552vazidmansuri005 wants to merge 5 commits intoaffaan-m:mainfrom
vazidmansuri005 wants to merge 5 commits intoaffaan-m:mainfrom
Conversation
Addresses affaan-m#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.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds a link to a new Antigravity guide in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR adds a new Key observations:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["./install.sh --target antigravity <modules>"] --> B["install-apply.js\n(planOperations)"]
B --> C{source path?}
C -->|"rules"| D["createFlatRuleOperations\n→ .agent/rules/ (flattened)"]
C -->|"commands"| E["createManagedScaffoldOperation\n→ .agent/workflows/"]
C -->|"agents"| F["createManagedScaffoldOperation\n→ .agent/skills/"]
C -->|"any other path\n(e.g. .agents)"| G["adapter.createScaffoldOperation\n(default scaffold, no special mapping)"]
D --> H[".agent/ecc-install-state.json\n(records all managed files)"]
E --> H
F --> H
G --> H
H --> I["node scripts/doctor.js\nDiagnose drift"]
I --> J["node scripts/repair.js\nRestore missing/drifted files"]
H --> K["node scripts/uninstall.js\nRemove ECC-managed files"]
Last reviewed commit: 68ca3f0 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/ANTIGRAVITY-GUIDE.md (1)
59-59: Clarify the full path foropenai.yaml.Line 59 states "Each skill in
.agents/skills/includes anagents/openai.yamlfile" but doesn't make the full nested path structure immediately clear.Consider revising to:
Each skill in `.agents/skills/` includes an `agents/openai.yaml` file at the path `.agents/skills/<skill-name>/agents/openai.yaml`:This makes it clearer that there's a nested
agents/subdirectory within each skill directory.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ANTIGRAVITY-GUIDE.md` at line 59, The sentence claiming "Each skill in `.agents/skills/` includes an `agents/openai.yaml` file" is ambiguous about the nested structure; update the wording for clarity by replacing it with a line that explicitly shows the nested path structure, e.g. state that each skill directory under `.agents/skills/` contains an `agents/openai.yaml` file and show the pattern `.agents/skills/<skill-name>/agents/openai.yaml`, referencing the strings `.agents/skills/` and `agents/openai.yaml` in the updated sentence.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ANTIGRAVITY-GUIDE.md`:
- Around line 114-125: The table's "Install target" cell uses the inconsistent
identifier `antigravity-project`; change it to `antigravity` to match the Quick
Start flags (`--target antigravity`) and the manifest "targets" arrays; update
the value in the Comparison with Other Targets table (the Install target row)
replacing `antigravity-project` with `antigravity` and verify no other table
cells or examples still use `antigravity-project`.
- Around line 107-109: Fix the typo where ".agents/" is used instead of the
correct ".agent/" in the guide and clarify the two-source workflow: update the
two occurrences that reference ".agents/skills/..." to ".agent/skills/..." and
explicitly state the three-step workflow as (1) main skill lives under
skills/your-skill-name/SKILL.md, (2) antigravity installer uses
agents/your-skill-name/agents/openai.yaml (installer auto-deploys this into the
runtime), and (3) manually mirror the SKILL.md content into
.agent/skills/your-skill-name/SKILL.md so the installer’s agents/ → .agent/ copy
is bridged; ensure the wording makes the manual copy step and the installer
behavior clear.
In `@README.md`:
- Line 833: Update the README line describing Antigravity to use the correct
adjective: change "flatten rules" to "flattened rules" in the Antigravity
description that references ".agent/" and the Antigravity Guide; ensure the
phrase reads "flattened rules" (e.g., in the string containing "**Antigravity**:
Tightly integrated setup for workflows, skills, and flatten rules in
`.agent/`.").
---
Nitpick comments:
In `@docs/ANTIGRAVITY-GUIDE.md`:
- Line 59: The sentence claiming "Each skill in `.agents/skills/` includes an
`agents/openai.yaml` file" is ambiguous about the nested structure; update the
wording for clarity by replacing it with a line that explicitly shows the nested
path structure, e.g. state that each skill directory under `.agents/skills/`
contains an `agents/openai.yaml` file and show the pattern
`.agents/skills/<skill-name>/agents/openai.yaml`, referencing the strings
`.agents/skills/` and `agents/openai.yaml` in the updated sentence.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 48201533-9d67-4ed0-8bca-b68d79300646
📒 Files selected for processing (2)
README.mddocs/ANTIGRAVITY-GUIDE.md
- 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
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/ANTIGRAVITY-GUIDE.md (1)
27-27:⚠️ Potential issue | 🟠 MajorFix inconsistent
.agentvs.agentspaths and source/runtime mapping.These lines mix
.agent/and.agents/and also blur source vs runtime paths. The current wording is self-contradictory and can send contributors to the wrong location. Use one consistent flow: source files in repo (agents/...+skills/...) and runtime destination (.agent/skills/...).Proposed doc correction
-> **Note**: The `skills/` directory is not directly mapped by the installer. Skill files in `.agents/skills/` are part of the repo's static layout and must be manually mirrored if you want them in the Antigravity runtime. +> **Note**: The `skills/` directory is not directly mapped by the installer. Skill files under `skills/` are part of the repo's static layout and must be manually mirrored into `.agent/skills/` if you want them available at runtime. -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: +For Antigravity support, the repo stores config at `agents/<skill-name>/agents/openai.yaml`; during install this is deployed to `.agent/skills/<skill-name>/agents/openai.yaml` for runtime use. -2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — the installer auto-deploys the `agents/` directory into `.agent/skills/` at runtime -3. Manually mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this is needed because the installer maps `agents/` → `.agent/skills/` but does not auto-transform `skills/` +2. Add the Antigravity agent config at `agents/your-skill-name/agents/openai.yaml` — the installer auto-deploys this into `.agent/skills/` at runtime +3. Manually mirror the `SKILL.md` content to `.agent/skills/your-skill-name/SKILL.md` — this is needed because the installer maps `agents/` → `.agent/skills/` but does not auto-transform `skills/`Also applies to: 60-60, 113-114
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ANTIGRAVITY-GUIDE.md` at line 27, Update the wording to consistently use the repo source paths "agents/" and "skills/" and the runtime destination ".agent/skills/" (remove ".agents/"). Specifically, replace any ".agents" occurrences with ".agent" and rephrase the sentence to state: source files live in the repository under "agents/" and "skills/" and must be mirrored to the runtime under ".agent/skills/" if you want them available to Antigravity; ensure similar corrections are applied to the other mentioned occurrences (lines referencing ".agent"/".agents" and source vs runtime mapping).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ANTIGRAVITY-GUIDE.md`:
- Around line 50-54: Update the example directory tree so it matches the
description that each skill uses a nested agents/openai.yaml; replace the flat
files listed under .agent/skills/ (planner.md, code-reviewer.md, tdd-guide.md)
with per-skill subdirectories that contain an agents/openai.yaml (e.g.,
.agent/skills/planner/agents/openai.yaml and corresponding README or
planner.md), and make the same change for the second occurrence (lines 58–60) so
the tree and the referenced openai.yaml paths are consistent.
---
Duplicate comments:
In `@docs/ANTIGRAVITY-GUIDE.md`:
- Line 27: Update the wording to consistently use the repo source paths
"agents/" and "skills/" and the runtime destination ".agent/skills/" (remove
".agents/"). Specifically, replace any ".agents" occurrences with ".agent" and
rephrase the sentence to state: source files live in the repository under
"agents/" and "skills/" and must be mirrored to the runtime under
".agent/skills/" if you want them available to Antigravity; ensure similar
corrections are applied to the other mentioned occurrences (lines referencing
".agent"/".agents" and source vs runtime mapping).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f8d0c193-9c66-4455-8597-e6ff160e249c
📒 Files selected for processing (2)
README.mddocs/ANTIGRAVITY-GUIDE.md
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
2 issues found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/ANTIGRAVITY-GUIDE.md">
<violation number="1" location="docs/ANTIGRAVITY-GUIDE.md:59">
P2: The guide documents conflicting skill layouts (flat `.agent/skills/*.md` vs per-skill `.agents/skills/<name>/agents/openai.yaml`), which will mislead users about the runtime structure.</violation>
<violation number="2" location="docs/ANTIGRAVITY-GUIDE.md:132">
P2: Troubleshooting incorrectly requires Markdown frontmatter for Antigravity files, conflicting with the documented `agents/openai.yaml` skill contract.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
- 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'
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/ANTIGRAVITY-GUIDE.md (3)
50-54:⚠️ Potential issue | 🟠 MajorDirectory tree conflicts with the documented
openai.yamlskill layout.Line 50-54 shows flat files under
.agent/skills/, but Line 60 says skills are directory-based with nestedagents/openai.yaml. These two models can’t both be true in the same “after install” example.Proposed doc fix
│ ├── skills/ -│ │ ├── planner.md -│ │ ├── code-reviewer.md -│ │ ├── tdd-guide.md +│ │ ├── planner/ +│ │ │ ├── SKILL.md +│ │ │ └── agents/openai.yaml +│ │ ├── code-reviewer/ +│ │ │ ├── SKILL.md +│ │ │ └── agents/openai.yaml +│ │ ├── tdd-guide/ +│ │ │ ├── SKILL.md +│ │ │ └── agents/openai.yaml │ │ └── ...Also applies to: 60-60
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ANTIGRAVITY-GUIDE.md` around lines 50 - 54, The directory tree example conflicts with the described skill layout: update the example so the skills are shown consistently as directory-based skills containing an agents/openai.yaml (or alternatively change the descriptive text to say skills are flat markdown files); specifically, align the listing under .agent/skills/ (the snippet showing planner.md, code-reviewer.md, tdd-guide.md) with the documented nested layout that references agents/openai.yaml by either converting those entries into per-skill directories (e.g., .agent/skills/planner/agents/openai.yaml) or changing the paragraph that mentions agents/openai.yaml to describe flat files, and make the same change where openai.yaml is mentioned so both examples match.
113-114:⚠️ Potential issue | 🟠 MajorCustom skill steps mix up source/runtime paths and installer behavior.
Line 113 says config lives in
.agents/skills/..., but then says installer deploysagents/into.agent/skills/. Line 114 then tells users to mirrorSKILL.mdinto.agents/skills/..., which conflicts with the earlier note that manual mirroring is needed for.agent/skills/runtime.Proposed wording fix
-2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — the installer auto-deploys the `agents/` directory into `.agent/skills/` at runtime -3. Manually mirror the `SKILL.md` content to `.agents/skills/your-skill-name/SKILL.md` — this is needed because the installer maps `agents/` → `.agent/skills/` but does not auto-transform `skills/` +2. Add the Antigravity agent config at `.agents/skills/your-skill-name/agents/openai.yaml` — the installer copies this config into `.agent/skills/` at runtime +3. Manually mirror the `SKILL.md` content to `.agent/skills/your-skill-name/SKILL.md` — this is needed because the installer handles agent config copy, but does not auto-transform `skills/` content🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ANTIGRAVITY-GUIDE.md` around lines 113 - 114, The docs confuse source vs runtime paths: update the two lines to consistently state that the source config and SKILL.md live under the repository source path `.agents/skills/your-skill-name/` and that the installer auto-deploys that directory into the runtime path `.agent/skills/your-skill-name/`; change the second sentence to instruct users to manually copy or mirror SKILL.md into the source `.agents/skills/your-skill-name/SKILL.md` only if they want a separate source file (or clarify that no manual mirroring is needed because the installer copies `.agents/` → `.agent/`), ensuring both lines consistently reference `.agents/` as the source and `.agent/` as the runtime target.
21-25:⚠️ Potential issue | 🟡 MinorUse one canonical source path name in the mapping section.
Line 25 maps
agents/→.agent/skills/, while Line 27 says ECC source is.agents/. Pick one canonical source path label here to avoid ambiguity in the core mapping table.Also applies to: 27-27
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ANTIGRAVITY-GUIDE.md` around lines 21 - 25, The mapping table uses two different source path labels for agents ("agents/" in the row mapping to ".agent/skills/" and ".agents/" elsewhere); pick a single canonical source path label and make all occurrences consistent (e.g., change all ".agents/" instances to "agents/" or vice versa). Update the mapping table row that contains agents/ → .agent/skills/ and any other referenced mappings so they use the exact same source path string ("agents/" or ".agents/") throughout the document to avoid ambiguity.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/ANTIGRAVITY-GUIDE.md`:
- Around line 50-54: The directory tree example conflicts with the described
skill layout: update the example so the skills are shown consistently as
directory-based skills containing an agents/openai.yaml (or alternatively change
the descriptive text to say skills are flat markdown files); specifically, align
the listing under .agent/skills/ (the snippet showing planner.md,
code-reviewer.md, tdd-guide.md) with the documented nested layout that
references agents/openai.yaml by either converting those entries into per-skill
directories (e.g., .agent/skills/planner/agents/openai.yaml) or changing the
paragraph that mentions agents/openai.yaml to describe flat files, and make the
same change where openai.yaml is mentioned so both examples match.
- Around line 113-114: The docs confuse source vs runtime paths: update the two
lines to consistently state that the source config and SKILL.md live under the
repository source path `.agents/skills/your-skill-name/` and that the installer
auto-deploys that directory into the runtime path
`.agent/skills/your-skill-name/`; change the second sentence to instruct users
to manually copy or mirror SKILL.md into the source
`.agents/skills/your-skill-name/SKILL.md` only if they want a separate source
file (or clarify that no manual mirroring is needed because the installer copies
`.agents/` → `.agent/`), ensuring both lines consistently reference `.agents/`
as the source and `.agent/` as the runtime target.
- Around line 21-25: The mapping table uses two different source path labels for
agents ("agents/" in the row mapping to ".agent/skills/" and ".agents/"
elsewhere); pick a single canonical source path label and make all occurrences
consistent (e.g., change all ".agents/" instances to "agents/" or vice versa).
Update the mapping table row that contains agents/ → .agent/skills/ and any
other referenced mappings so they use the exact same source path string
("agents/" or ".agents/") throughout the document to avoid ambiguity.
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/ANTIGRAVITY-GUIDE.md">
<violation number="1" location="docs/ANTIGRAVITY-GUIDE.md:27">
P2: The added Antigravity note incorrectly describes installer source path as `.agents/`, contradicting actual mapping from `agents/` and creating misleading setup instructions.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
- 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.
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/ANTIGRAVITY-GUIDE.md">
<violation number="1" location="docs/ANTIGRAVITY-GUIDE.md:114">
P1: Contributor instructions for Antigravity skills omit updating `agents/`, so following them may not produce a deployable Antigravity runtime skill.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
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.
Author
|
@affaan-m Ready for review — all bot feedback has been addressed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/ANTIGRAVITY-GUIDE.mdCloses #462
What's Covered
.agent/rules/, commands →.agent/workflows/, agents →.agent/skills/)openai.yamlagent config format explanationType
Testing
scripts/lib/install-targets/antigravity-project.jsSELECTIVE-INSTALL-ARCHITECTURE.mdandSELECTIVE-INSTALL-DESIGN.mdopenai.yamlformat from existing skills in.agents/skills/Checklist
Summary by cubic
Adds an Antigravity setup and usage guide at docs/ANTIGRAVITY-GUIDE.md and links it from the README to help users install and use ECC with
.agent/. Closes #462..agents/(ECC source) vs.agent/(Antigravity runtime), the explicit mappings (rules/,commands/,agents/→.agent/...), and that.agents/is a static repo layout (not installer-mapped); removed theskills/mapping row; added the missingagents/step to the contributor workflow so skills deploy to.agent/skills/; fixed.agent/path references; documented the full nestedopenai.yamlpath.antigravity; Cursor Agents/Skills marked N/A; rules called out as flattened; fixed install management flow (doctor.jsdiagnoses,repair.jsrestores) and standardized uninstall tonode scripts/uninstall.js; updated README wording and linked to the guide.Written for commit 68ca3f0. Summary will update on new commits.
Summary by CodeRabbit