Everyone's Talking About Gemini 3.5 Flash. The Real Story at Google I/O 2026 Was a Skill File.
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.mdcontaining routing rules, validation thresholds, and error formatting instructions - Validation Engine:
validate-contract.ts(TypeScript) that parsesopenapi.yaml, extracts route definitions, and compares them against Express/Fastify handler signatures - VCS Integration: A
pre-pushhook 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 listto 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.mdand 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
- Install the runtime: Download Antigravity CLI from the official distribution channel or use your system package manager. Verify installation with
agy --version. - Initialize in your project: Navigate to your repository root and run
agy. The CLI scans your dependency tree and loads available skills. - Explore built-in primitives: Execute
/skillsto view the 129 pre-packaged behaviors. Filter by category or search for your use case. - 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.
- Commit and enforce: Add the generated
SKILL.mdand scripts to version control. The hook activates automatically on subsequent pushes, enforcing your standard without manual intervention.
Mid-Year Sale β Unlock Full Article
Base plan from just $4.99/mo or $49/yr
Sign in to read the full article and unlock all tutorials.
Sign In / Register β Start Free Trial7-day free trial Β· Cancel anytime Β· 30-day money-back
