Beyond Autocomplete: Building Persistent Agent Behaviors with Antigravity CLI Skill Files

Current Situation Analysis

The developer tooling landscape has spent the last three years optimizing for conversational assistance and inline code completion. Teams treat AI coding assistants as ephemeral chat windows: you ask a question, get a snippet, paste it, and move on. This model creates a persistent gap between AI suggestion and repository enforcement. AI can recommend best practices, but it rarely persists those standards into the development lifecycle without manual CI/CD configuration.

This problem is overlooked because industry coverage fixates on model benchmarks. At Google I/O 2026, headlines centered on Gemini 3.5 Flash performance metrics, Veo 3 video generation, and multimodal reasoning capabilities. While technically impressive, these metrics describe what the model can do in isolation. They ignore the runtime architecture that determines how developers actually operationalize AI in production.

The shift became visible through two concrete developments. First, Google announced the retirement of Gemini CLI for consumer tiers on June 18, 2026, replacing it with Antigravity CLI. Second, Antigravity introduced a strict separation of concerns: agent behavior is defined in JSON (agent.json), while reusable capabilities are defined in Markdown (SKILL.md). The runtime ships as a compiled Go binary with zero Node.js dependencies, supports multi-model routing (Gemini 3.5 Flash via the Managed Agents API, plus Claude and GPT-OSS locally), and includes 129 pre-packaged behavioral primitives. This architecture signals a platform transition from transient AI assistance to persistent, version-controlled agent behaviors that execute autonomously within your repository.

WOW Moment: Key Findings

The architectural shift becomes clear when comparing traditional AI development assistants against the Antigravity skill file model. The table below isolates the operational differences that impact production workflows.

Approach	Execution Model	Persistence	Model Routing	Governance Scope
Traditional AI Assistant	Ephemeral chat / inline completion	None (discarded after session)	Single-model or manual provider switching	Developer discretion
Antigravity Skill Files	Repository-level hooks / background agents	Version-controlled Markdown + JSON	Multi-model routing (Gemini 3.5 Flash, Claude, GPT-OSS)	Workspace / Global / Shared priority resolution

This finding matters because it transforms AI from a suggestion engine into a repository enforcement layer. Instead of relying on developers to remember to run linters, validate schemas, or check accessibility standards, the skill file compiles instructions into executable hooks and validation scripts. The behavior compounds: every commit, push, or PR triggers the same standardized checks without manual orchestration. Teams gain deterministic quality gates powered by LLM reasoning, backed by static analysis, and enforced at the VCS layer.

Core Solution

Implementing a persistent agent behavior requires understanding the JSON/Markdown split and leveraging the CLI's proposal-to-execution workflow. Below is a production-ready implementation of an API contract validator that enforces OpenAPI compliance before code reaches the remote repository.

Step 1: Define the Skill Intent

Launch Antigravity CLI in your project root and issue a natural language directive. The runtime parses the prompt, scans your dependency tree, and cross-references existing skills.

agy
> create a skill that validates all incoming route handlers against the OpenAPI 3.1 specification before pushing to remote

Step 2: Review the Execution Plan

The agent does not execute blindly. It generates a structured proposal:

• Skill Definition: SKILL.md containing routing rules, validation thresholds, and error formatting instructions
• Validation Engine: validate-contract.ts (TypeScript) that parses openapi.yaml, extracts route definitions, and compares them against Express/Fastify handler signatures
• VCS Integration: A pre-push hook that triggers the validator, formats output, and blocks the push on critical mismatches
• Self-Verification: A synthetic route with intentional contract violations to confirm hook behavior

Step 3: Approve and Execute

After reviewing the file paths and logic, confirm execution:

> proceed

The runtime generates the following structure:

your-project/
├── .agents/
│   └── skills/
│       └── api-contract-enforcer/
│           ├── SKILL.md
│           └── scripts/
│               └── validate-contract.ts
└── .git/
    └── hooks/
        └── pre-push

Step 4: Runtime Execution & Verification

The generated SKILL.md instructs the agent to monitor staged route files, extract handler metadata, and compare against the specification. The TypeScript validator uses openapi-types and fastify/express type introspection to detect mismatches in parameters, response schemas, and HTTP methods.

When a developer pushes, the hook executes:

> git push origin main
Validating API contract against openapi.yaml...
[CRITICAL] Route /api/v1/users expects response schema UserList, got UserSingle
[WARNING]  Route /api/v1/health missing rate-limit header documentation
→ Push blocked. Resolve 1 critical violation or use --no-verify to bypass.

The hook cleans up temporary validation artifacts, logs the result, and exits with a non-zero status code. The developer fixes the handler, stages the correction, and pushes again. The cycle repeats deterministically.

Architecture Rationale

• JSON for Agents, Markdown for Skills: Agent configuration (agent.json) handles state, memory, and execution permissions. Skill definitions (SKILL.md) remain human-readable, diff-friendly, and easily version-controlled. This separation prevents configuration drift and enables team-wide skill sharing.
• Go Binary Runtime: Compiling the CLI to Go eliminates Node.js dependency conflicts, reduces startup latency, and ensures consistent behavior across CI runners and developer machines.
• Hook-Based Enforcement: Pre-push hooks catch violations before network transmission, reducing CI waste and preventing broken contracts from entering shared branches.
• Multi-Model Routing: Local validation scripts run statically. LLM reasoning is reserved for complex schema inference and error explanation, routed through Gemini 3.5 Flash, Claude, or GPT-OSS based on team preference and cost constraints.

Pitfall Guide

1. Blind Approval of Execution Plans

Explanation: The proceed command triggers file creation, hook installation, and repository modifications. Approving without reviewing the generated plan can overwrite existing hooks or introduce unintended dependencies. Fix: Always run git diff after the proposal phase. Verify file paths, script contents, and hook targets before confirming. Use --dry-run flags when available to preview changes.

2. Scope Collision Between Workspace and Global Skills

Explanation: Skills created in the global directory (~/.gemini/antigravity-cli/skills/) apply to every project on the machine. Project-specific rules bleeding into unrelated repositories cause false positives and validation noise. Fix: Explicitly target workspace scope during creation. Use the CLI's scope selector or manually place SKILL.md under .agents/skills/ within the project root. Audit global skills quarterly and remove stale definitions.

3. Ignoring Priority Resolution Order

Explanation: Antigravity resolves skills using a strict precedence: Workspace → Global → Shared. Developers often assume the most recently created skill takes priority, leading to unexpected behavior when multiple definitions exist. Fix: Document your team's scope strategy. Use workspace skills for project-specific contracts, global skills for organization-wide standards, and shared skills for cross-team utilities. Verify resolution order with /skills list --verbose.

4. Runtime Dependency Mismatch

Explanation: The Go binary runtime does not manage Node.js or Python dependencies required by generated validation scripts. Missing npm install steps or incompatible package versions cause hook failures in CI environments. Fix: Bundle dependency installation into the skill's setup phase. Include a setup.sh or postinstall script that validates required runtimes. Pin package versions in package.json and lockfiles. Test hooks in isolated CI runners before team rollout.

5. Closed-Source Trust Gap

Explanation: Antigravity CLI is closed-source, unlike its predecessor. The runtime executes generated scripts and manages file system access without community auditability. Enterprise environments require transparency for compliance and security reviews. Fix: Treat generated hooks as third-party code. Audit script contents, enforce signature verification, and run validation in sandboxed containers. Maintain an internal registry of approved skills and require security team sign-off before global deployment.

6. Hook Performance Degradation

Explanation: LLM-powered validation introduces latency. Running complex schema comparisons on every push slows developer feedback loops and encourages --no-verify bypasses. Fix: Implement incremental validation. Cache OpenAPI parse results, skip unchanged files, and run static checks first. Reserve LLM reasoning for error explanation and complex inference. Set timeout thresholds and fail fast on critical violations.

7. Skill Drift and Version Incompatibility

Explanation: As APIs evolve, OpenAPI specifications change. Stale SKILL.md definitions reference outdated routes, schemas, or validation rules, causing persistent false failures. Fix: Version control skill files alongside your codebase. Add automated update triggers that parse specification changes and suggest skill adjustments. Schedule quarterly skill audits to align validation rules with current architecture.

Production Bundle

Action Checklist

• Audit existing skills: Run /skills list to identify built-in and custom definitions before creating new ones
• Define scope boundaries: Decide whether the skill belongs in Workspace, Global, or Shared directories
• Review execution plan: Verify file paths, script logic, and hook targets before approving
• Test in isolation: Run the hook against a synthetic branch with intentional violations
• Commit and document: Add SKILL.md and supporting scripts to version control with clear README instructions
• Monitor CI performance: Track hook execution time and false positive rates over the first two weeks
• Schedule quarterly audits: Align skill definitions with API changes, framework updates, and team standards

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Project-specific validation rules	Workspace-scoped SKILL.md	Prevents cross-project contamination and reduces noise	Low (local execution only)
Organization-wide compliance standards	Global-scoped SKILL.md	Ensures consistent enforcement across all repositories	Medium (requires governance overhead)
Multi-team shared utilities	Shared-scoped SKILL.md	Centralizes maintenance and reduces duplication	Low (cached execution)
High-frequency push workflows	Static validation + async LLM explanation	Minimizes hook latency while preserving reasoning quality	Low (reduced CI wait time)
Enterprise compliance requirements	Closed-sandbox execution + script auditing	Meets security review standards and audit trails	High (infrastructure and review costs)

Configuration Template

# SKILL.md: API Contract Enforcer
## Purpose
Validate all route handlers against the OpenAPI 3.1 specification before pushing to remote repositories.

## Execution Rules
1. Parse `openapi.yaml` and extract route definitions, parameters, and response schemas
2. Compare staged route files against extracted definitions
3. Flag critical mismatches (method, path, response schema) as blocking errors
4. Flag warnings (missing headers, deprecated endpoints) as informational
5. Output formatted table to console and exit with non-zero status on critical violations

## Validation Script
- Language: TypeScript
- Entry: `scripts/validate-contract.ts`
- Dependencies: `openapi-types`, `typescript`, `@types/node`
- Timeout: 15 seconds

## Hook Integration
- Type: pre-push
- Trigger: `git push`
- Bypass: `--no-verify` (requires team lead approval)
- Cleanup: Remove temporary validation artifacts after execution

## Version Control
- Track: `.agents/skills/api-contract-enforcer/`
- Update Trigger: Specification changes or framework upgrades
- Review Cycle: Quarterly

Quick Start Guide

1. Install the runtime: Download Antigravity CLI from the official distribution channel or use your system package manager. Verify installation with agy --version.
2. Initialize in your project: Navigate to your repository root and run agy. The CLI scans your dependency tree and loads available skills.
3. Explore built-in primitives: Execute /skills to view the 129 pre-packaged behaviors. Filter by category or search for your use case.
4. Create your first skill: Issue a natural language prompt describing the validation rule or automation you need. Review the proposal, confirm execution, and test against a synthetic branch.
5. Commit and enforce: Add the generated SKILL.md and scripts to version control. The hook activates automatically on subsequent pushes, enforcing your standard without manual intervention.