Antigravity Optimization Tips
Best practices for maximizing agent effectiveness while keeping context costs low.
Context Window Management
Every "Always On" rule consumes tokens on every conversation. Context window management is the single biggest lever for agent performance and cost.
Minimize Always On rules
Only meta-learning and critical governance rules need alwaysApply: true. Everything else should use glob patterns or model-decision activation. This is documented in the Antigravity Rules documentation.
Use specific glob patterns
Instead of broad patterns like **/*, use targeted globs: **/*.tsx for React rules,**/api/**/*.ts for backend rules. This ensures rules only activate when relevant files are in context.
Write descriptive model-decision descriptions
When using model-decision activation, the description field is what the model reads to decide whether to apply the rule. Make it specific: "Apply when writing database queries or modifying schema" is better than "Database stuff."
Keep rules under 12,000 characters
Antigravity enforces a per-file character limit. If a rule is approaching this limit, it's probably doing too much. Split it into focused sub-rules with their own activation patterns.
Rule Design Principles
✅ Do: Use concrete examples
"Use const by default. Use let only when reassignment is needed. Never use var." This is specific and testable.
❌ Don't: Be vague
"Write clean code." This is subjective and unenforceable. The agent can't reliably follow instructions it can't verify.
✅ Do: State what to do AND what not to do
"Always use named exports. Never use default exports except for page components." Both sides of the constraint make it clearer.
❌ Don't: Write rules you won't enforce
If you never check whether the agent follows a rule, remove it. Unenforced rules add noise without value.
Skill Optimization
Write clear "When to Use" sections
Antigravity's progressive disclosure reads skill descriptions first, then loads the full SKILL.md only when relevant. A clear "When to Use" section helps the agent decide accurately. See the Skills documentation.
Include edge cases
Skills that only cover the happy path break on real work. Add sections for "What to do when X fails" or "Edge cases to watch for."
Reference rules from skills
You can use @filename in Antigravity files to reference other files. A deploy skill can reference your testing-standards rule to ensure tests pass before deployment.
Bundle helper scripts with skills
Skills can include scripts/, examples/, and resources/ folders alongside SKILL.md. The agent can read these for reference implementations and templates.
Common Pitfalls
Too many Always On rules
Every Always On rule consumes context tokens regardless of relevance. Aim for 2-4 Always On rules maximum. Move domain-specific rules to glob or model-decision activation.
Contradictory rules
If one rule says "always use arrow functions" and another says "use function declarations for hoisting," the agent will behave unpredictably. Run the Brain Audit Checklist to catch conflicts.
Stale skills after project changes
When your project structure, dependencies, or deployment process changes, update corresponding skills immediately. A skill with outdated steps is worse than no skill — it produces confident but wrong output.
Treating global rules as workspace rules
Global rules (~/.gemini/GEMINI.md) apply to every Antigravity workspace. Only put truly universal preferences there (language, communication style). Project-specific rules belong in .agents/rules/.
The Key Insight
This template was last reviewed in April 2026 against the official Antigravity rules & workflows docs. Spot something out of date? Let us know.