How to Automate Google Antigravity Audits: Build Self-Maintenance Custom Skills and Rules

Created date: 2026/07/12, Update date: 2026/07/12

As you customize AI assistants like Google Antigravity, rules and skills can grow too numerous to manage.
This article describes how to build a self-maintenance custom skill (antigravity-audit) that lets the AI agent review and automatically optimize its own configurations.

Table of Contents

Overview
The “Configuration Chaos” Problem
Designing antigravity-audit
1. Key Features
2. 🔄 The Execution Process Flow
🔍 Specific Audit Viewpoints Scanned by antigravity-audit
1. 1. Static Validation (Programmatic Checks)
2. 2. AI Qualitative Review & Tuning Proposals (LLM-driven Checks)
🌐 Automated Syncing of “External Specs & Rules” via Selenium
1. Execution Process
📊 A Real-world Audit Report Example
🛠️ The Mechanics of “Auto-fix”
🔄 Daily Development & Workflow Integration
🔗 GitHub Repository
Conclusion

Automate Google Antigravity Audit: How to build self-maintenance custom skills

Overview

As you use AI coding assistants (such as Google Antigravity or Claude Code), you will notice configuration files and custom skills accumulating rapidly. This can lead to what is known as “configuration chaos.” In this article, we introduce how to build a self-maintenance custom skill called antigravity-audit , which scans, diagnoses, and optimizes your configurations automatically, alongside clean portable design patterns.

The “Configuration Chaos” Problem

The introduction of AI coding assistants often leads to a quick buildup of behavior rules (e.g., RULES.md, AGENTS.md) and custom scripts (e.g., SKILL.md) in both project-local and user-global folders.

This rapid growth introduces several management challenges:
1. Outdated Rules : Obsolete instructions stay active, cluttering the AI’s context window.
2. Broken Skills : Missing script references or outdated dependencies break execution.
3. Desynchronized Bilingual Docs : Doc updates in one language leave the other language outdated.

Manually reviewing these files is tedious. An elegant solution is to delegate the audit of AI configurations to the AI assistant itself .

Designing `antigravity-audit`

The antigravity-audit custom skill scans target directories, diagnoses configurations and skills, creates a clean Markdown diagnostic report, and attempts to auto-fix minor issues.

Key Features

Bilingual Workspace Detection :
Scans root files (e.g., SKILL.md, README.md) to detect the ratio of Japanese characters. Based on this ratio, the skill dynamically determines whether to output the audit report in Japanese or English.
Skill Integrity Check :
Verifies if YAML frontmatter contains required attributes ( name , description ) and flags dead script references.
Rule Deduplication :
Scans for redundant rules across global and project levels, suggesting clean-ups.

🔄 The Execution Process Flow

The following diagram illustrates the sequence of actions from triggering the audit skill to applying environment patches.

sequenceDiagram autonumber actor Developer as Developer participant Audit as audit.py participant Selenium as Selenium (Headless) participant Spec as Spec Site (Web) participant Agent as AI Agent (LLM) participant Patch as apply_patch.py Developer->>Audit: Launch Skill (python3 scripts/audit.py) rect rgb(240, 248, 255) note right of Audit: Self-Update Phase Audit->>Selenium: Instruct Spec Scraping Selenium->>Spec: Fetch Live Guidelines (Antigravity 2.x) Spec-->>Selenium: Rendered Page DOM Selenium-->>Audit: Crawled Spec Data (Markdown/JSON) note right of Audit: Compare and self-update script if out-of-date end rect rgb(245, 245, 245) note right of Audit: Workspace Scan Phase Audit->>Audit: Scan target folder (.agents/) Audit->>Audit: Detect document language ratio end rect rgb(255, 245, 238) note right of Audit: Verification & Review Phase Audit->>Audit: Run static validations (YAML/JSON schema, Sidecar, MCP etc) Audit-->>Agent: Present static result and file list Agent->>Agent: Run LLM Qualitative Review (analyzing Hooks, Subagents, etc) Agent-->>Audit: Return Qualitative Tuning proposals end Audit-->>Developer: Output Audit Report (audit_report.md) Developer->>Developer: Review suggestions and approve patch Developer->>Patch: Run Patch Command (python3 apply_patch.py --patch [file]) Patch-->>Developer: Safely apply changes to target files

① Self-Update Phase :
To ensure synchronization with the latest guidelines, the skill initiates a Selenium-based crawl of the official specifications on startup, automatically patching and restarting itself if a mismatch occurs.
② Workspace Scan Phase :
Discovers global and project-level .agents/ settings, parsing Japanese/English ratios to format output reports in the correct target language.
③ Verification & Review Phase :
Runs programmatic checkers (schema layout, MCP endpoints, hooks syntax, Sidecar keys), then transfers data to the AI agent to produce qualitative optimizations based on the Tuning Checklist.
④ Report & Patch Application :
Saves the Markdown audit report ( audit_report.md ) for user verification. Once approved, the patch is applied safely using apply_patch.py .

🔍 Specific Audit Viewpoints Scanned by `antigravity-audit`

To prevent AI development environments from deteriorating, the skill performs checks combining programmatic “static validation” and “AI qualitative review” powered by the LLM.

1. Static Validation (Programmatic Checks)

Using audit.py and diagnostic submodules, the following items are automatically verified:

Evaluation Item	Check Details	Goal / Purpose
Schema Conformance	Checks if `SKILL.md` contains valid YAML frontmatter and proper JSON syntax/mandatory attributes.	To ensure the system correctly parses and loads custom skills.
Rule Description Rule	Validates if the `description` in rule frontmatter ( `rules/*.md` ) is within 150 characters.	To maintain clean list readability in UI environments.
Physical Duplication	Detects duplicate rules or skill files physically copied across global ( `~/.gemini/config/` ) and local ( `.agents/` ) locations.	To prevent configuration conflicts and prune redundant files.
Sidecar Enablement ⚡	If `sidecar.json` exists, verifies if `sidecars.<id>.enabled` is set to `false` in `~/.gemini/config/config.json` .	To prevent background daemons from failing to start due to missing configuration keys.
Plugin Placement ⚡	Verifies if plugins are correctly positioned in supported paths: `.agents/plugins/` or `_agents/plugins/` .	To prevent runtime plugin loading exceptions.
MCP Schema Check ⚡	Checks if remote configurations in `mcp_config.json` use the valid `serverUrl` field instead of unsupported fields.	To avoid remote connection exceptions with external MCP hosts.
Hook AgentStop Validation ⚡	Ensures that `AgentStop` events defined in `hooks.json` return a JSON output containing the `decision` field.	To prevent abrupt termination of execution flow from unhandled hooks.
brain Log History Analysis ⚡	Scans recent session logs and error occurrences to dynamically diagnose Antigravity configuration optimizations (AUD-08 to AUD-10).	To automatically address repetitive compilation/run exceptions and workflow friction.

2. AI Qualitative Review & Tuning Proposals (LLM-driven Checks)

After running static checks, the AI agent reviews the configuration files to propose structural improvements:

Evaluation Item	Check Details	Goal / Purpose
Hook Conversion	Proposes migration of Linter, formatting, or test script runs into `hooks.json` events instead of active skill steps.	To automate critical assertions and avoid manual execution oversights.
Global/Local Placement	Suggests moving reusable, general guidelines to global settings and project-specific contexts to project-local paths.	To optimize context window usage and improve rule reuse.
Sidecar Migration	Proposes wrapping background listeners or recurring cron-jobs into `sidecar.json` structures to run as system daemons.	To offload blocking operations from active conversation runs.
Subagent Delegation	Proposes offloading heavy operations (like massive codebase scans or E2E tests) using `invoke_subagent` to child agents.	To bypass the parent context window limit (65,536 tokens) and run async tasks.
Plugin Packaging	Recommends packaging related skills, rules, MCP settings, and hooks into one namespace-separated plugin.	To simplify custom feature management and distribute settings cleanly.
Least-privilege Permission	Suggests narrowing down wildcard ( `*` ) execution permissions to specific command prefixes or directories.	To maintain sandbox integrity and prevent hazardous command runs.
Logical Consolidation	Resolves rules that share similar instructions under different filenames, merging them using “As-Is -> To-Be” comparison tables.	To prune redundant guidelines and keep the rule token footprint small.
Failsafe Hook	Recommends hooks that block agents trying to commit with `--no-verify` or modify setup configurations.	To avoid accidental bypass of verification standards.
Memory Consistency	Validates consistency between progress files ( `task.md` ) and state cache JSONs.	To keep the agent’s progress indicators in sync.
Hook Cost Assessment	Audits hook timeouts and quantities to avoid response latency and unnecessary token billing.	To optimize developer experience (DX) by avoiding slow roundtrips.
Rule/Skill Recommendations	Proposes custom rules/skills matching the project’s unique tech stacks or APIs (e.g., Vertex AI).	To guard against tech-stack specific pitfalls and speed up implementation.

🌐 Automated Syncing of “External Specs & Rules” via Selenium

Another critical pillar of rule auditing is “ruleset freshness management” .
Official specifications for cloud services like AWS and GCP, as well as AI tool documentations (such as Antigravity itself), receive frequent updates. If rules saved locally ( RULES.md ) remain static, the AI assistant will continue generating outdated configurations and deprecated command invocations.

To combat this, antigravity-audit supports automatic web crawling and scraping of official specification sites using Selenium (headless Chrome) to fetch the latest guidelines.

Execution Process

Dynamic Document Fetching : Selenium controls a headless Chrome instance to navigate public reference sites or release notes that lack standardized APIs, converting HTML tables/docs into Markdown or JSON.
Difference Detection : Parses and compares local rules (e.g., port_allocation.md port tables or command parameters) against the crawled live specs.
Automated Rule Patching : Alerts the user of deprecated commands or updated endpoints in the audit report, generating a patch file for fields that can be automatically updated.

This mechanism ensures your local rule context remains synced with the latest industry specifications without human intervention.

📊 A Real-world Audit Report Example

Here is an example of the actual Markdown report output generated when running antigravity-audit . It uses visual alerts ( ❌ Error , ⚠️ Warning ) and GitHub-style alerts to make issues easily identifiable.

# 🛡️ Antigravity Environment Audit Report

> [!NOTE]
> Scan completed at: 2026-07-12 19:40:00 (JST)
> Detected primary language: English (en)

## 📈 Diagnostic Summary

| Category | Checks Run | Issues Found | Auto-fix Status |
| :--- | :---: | :---: | :---: |
| Global Rules (AGENTS.md) | 12 | 1 | 🛠️ Auto-fixed |
| Project Rules (RULES.md) | 8 | 0 | ✅ No issues |
| Custom Skills (skills/) | 15 | 2 | ⚠️ Action Required |

---

## 🚨 Diagnostic Alert Details

### 1. Duplicate Rule in Global Settings
- **File**: `~/.gemini/config/AGENTS.md`
- **Status**: `⚠️ Warning`
- **Details**: The rule forbidding "Chrome automation" duplicates a project-level definition in `.agents/RULES.md`.
- **Action**: Automatically removed the duplicate rule section from the global configuration to optimize context. (**Auto-fix completed**)

### 2. Missing YAML Frontmatter Field in Custom Skill
- **File**: `skills/aws-deploy/SKILL.md`
- **Status**: `❌ Error`
- **Details**: Missing the mandatory `description` field required by the skill loader.
- **Action**: Please open `skills/aws-deploy/SKILL.md` manually and add a suitable description to its frontmatter block.

### 3. Broken Executable Reference in Custom Skill
- **File**: `skills/house-keeping/SKILL.md`
- **Status**: `❌ Error`
- **Details**: The helper script `scripts/cleanup.sh` referenced in `SKILL.md` is missing or lacks executable permissions.
- **Action**: Check if the file exists and verify if `chmod +x` has been run.

🛠️ The Mechanics of “Auto-fix”

Beyond simply reporting issues, antigravity-audit can safely resolve specific configurations:

Auto-populating YAML Frontmatter :
If a SKILL.md lacks YAML frontmatter, the AI model parses the skill content, dynamically deduces a name and description, and inserts the frontmatter block at the top of the file automatically.
Merging Redundant Rules :
When identical rules exist globally and locally, it comment-outs or cleans the lower-priority global rules, helping keep token consumption to a minimum.

🔄 Daily Development & Workflow Integration

We recommend integrating this audit workflow into your daily development cycle:

Weekly or Monthly Regular Reviews (Recommended) :
Since rule context and skills grow continuously, schedule a weekly or monthly maintenance day to run the audit script. This allows environment health checkups and cleanup tasks without slowing down local commit speed (DX).
CI/CD Pipeline Integration :
Run the audit script automatically in CI/CD environments (e.g., GitHub Actions) upon Pull Request creation or merges to verify that rules and skills are correctly formatted without slowing down local commit speed.
Manual On-Demand Directive :
When beginning a session with an AI agent, request the scan using a simple prompt:
> “Run the automatic audit skill to scan my current custom skills and rules. Resolve any redundant rules or formatting errors automatically.”

🔗 GitHub Repository

The configuration templates for the auto-audit skill and the source code of this blog are available on the following GitHub repository:

👉 kanji-shinohara/web-gcp-us-firebase-moderniser-repo

Conclusion

To maximize the efficiency of AI coding agents, our development environment must stay organized and optimized. Delegating self-maintenance tasks to custom skills frees developers to focus on active coding.