Configuring Custom Workspace Skills in Google Antigravity: Multi-Agent Isolation and Scoping

What Are Custom Workspace Skills in Google Antigravity?

Custom workspace skills in Google Antigravity are project-bound capability bundles containing a SKILL.md manifest, optional executable scripts, reference templates, and input schemas that extend the autonomous reasoning of Google Antigravity agents within a designated repository. Unlike ambient rules that continuously occupy context, workspace skills remain dormant in the repository until explicitly matched by agent intent or invoked by user command.

According to the official Anthropic Claude Code Documentation: “Skills are modular packages containing a SKILL.md file and optional supporting files that provide reusable instructions, scripts, and context.” Google Antigravity adopts this standardized architecture while extending it to multi-agent orchestrations. By encapsulating domain procedures—such as repository-specific database migrations, proprietary Kubernetes deployments, or custom test harnesses—workspace skills turn general-purpose reasoning models into specialized domain engineers without leaking proprietary instructions into your global environment.

In production environments, developers often struggle with skill pollution when hundreds of instructions accumulate in a single global directory. Google Antigravity resolves this challenge by enforcing strict scoping boundaries between global machine skills, plugin packages, and repository-level workspace skills. To compare how Antigravity handles ambient guidelines versus executable tools, review our companion analysis of Google Antigravity rules and workspace scopes.

How Does Workspace Scoping Differ From Global ~/.gemini/antigravity Skills?

Workspace scoping isolates skill discovery to the current repository root, whereas global skills in ~/.gemini/antigravity/skills/ are indexed across every session on that computer. This architectural separation ensures that experimental scripts, breaking schema updates, and client-specific secrets remain confined to the repository where they belong.

Google Antigravity implements a hierarchical directory walk to resolve skills during agent initialization. The runtime checks three distinct tiers:

1. Workspace Local Scope (<workspace-root>/.gemini/skills/ or skills/): Highest precedence. Contains repo-specific workflows, deployment assertions, and specialized CI helpers. Skills defined here override identically named global skills.
2. Plugin and Sidecar Scope (~/.gemini/config/plugins/<plugin>/skills/): Medium precedence. Installed via namespaced plugin bundles that deliver toolchains, third-party MCP servers, or framework integrations.
3. Global User Scope (~/.gemini/antigravity/skills/ and builtin): Lowest precedence. Houses cross-cutting developer skills such as git commit hygiene, generic unit test drafting, and code formatting rules.

By restricting execution-heavy scripts to workspace scope, teams prevent dangerous side effects. For example, an automated database rollback script intended for an internal staging project cannot be accidentally triggered by an Antigravity agent working in a client's production monorepo. For an architectural deep dive into cross-agent folder layouts, read our guide on building a cross-agent skill library.

Scoping Architecture: Inherit, Branch, and Share Workspace Modes

Google Antigravity enables autonomous multi-agent execution where a parent planner coordinates specialized subagents to complete complex development milestones. When launching a subagent via the invoke_subagent API, Antigravity supports three discrete workspace isolation modes that determine how skills and file modifications propagate:

• 1. Inherit Mode (Workspace: 'inherit'): The default configuration. The subagent operates directly within the parent agent's workspace directory. All workspace skills located in .gemini/skills/ are immediately accessible, and file writes occur in-place. Use this mode for sequential refactoring tasks and documentation audits where zero environment setup overhead is required.
• 2. Branch Mode (Workspace: 'branch'): The runtime creates an isolated temporary directory cloned or branched from the parent workspace. The subagent inherits the workspace skills snapshot but executes in strict isolation. When the subagent terminates or encounters a failure, the branched directory is safely deleted, guaranteeing that unverified skill runs or destructive script tests never pollute the main repository.
• 3. Share Mode (Workspace: 'share'): Similar to a Git worktree or Mercurial share (hg share), this mode shares the parent repository's underlying object storage while maintaining an independent working branch. Subagents access shared workspace skills without duplicating gigabytes of node_modules or build artifacts on disk.

Selecting the correct workspace mode is vital when authoring skills that execute destructive shell commands or run database seeders. For a comprehensive architectural comparison of multi-agent execution flows, review our guide to Google Antigravity workflows vs Claude Code subagents.

The Sprawl Moment: The Leaked Production Skill and the Cross-Workspace Collision

A backend engineering lead oversees two critical microservices: a legacy payment gateway that requires manual PostgreSQL schema locks before applying migrations, and an experimental event-driven microservice using DynamoDB. While troubleshooting a deadlocked transaction on a Friday afternoon, the engineer writes a custom Antigravity skill named db-migrate. Because they save the skill in their global user directory (~/.gemini/antigravity/skills/db-migrate/SKILL.md) rather than scoping it to the payment gateway's .gemini/skills/ folder, the skill becomes globally active across all workspaces. The following Monday, while refactoring the event microservice in an isolated session, the engineer instructs Antigravity to run database migrations. The agent locates the global db-migrate skill, assumes it applies to the current workspace, and attempts to execute relational DDL statements against non-existent PostgreSQL connection strings. The agent enters an error retry loop, executes an unverified rollback assertion, and corrupts local staging configuration files, stalling development velocity for three hours while the engineer dissects why an unrelated payment script executed in an event processing repo.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

How Do You Author a Custom Antigravity Workspace Skill?

You author a custom Antigravity workspace skill by creating a dedicated directory inside your project root at .gemini/skills/<skill-name>/ containing a standardized SKILL.md manifest formatted with YAML frontmatter. The manifest declares the skill name, an actionable description explaining activation triggers, and optional parameter constraints.

Conforming to the Semantic Versioning 2.0.0 specification, including explicit version tags in your frontmatter ensures that multi-agent pipelines can verify skill compatibility before execution. Below is a production-grade workspace skill designed for API contract verification:

---
name: verify-api-contract
description: Runs Spectral OpenAPI linter and Prism mock assertions against local API schemas.
triggers:
  - "/verify-api"
  - "lint openapi"
  - "validate schema"
version: 1.2.0
---

# API Contract Verification Playbook

## Objective
Validate that modified endpoints conform to the OpenAPI 3.1 specification before opening a pull request.

## Execution Sequence
1. Locate updated OpenAPI definitions under `specs/v1/`.
2. Execute the Spectral validation suite:
   ```bash
   npm run lint:spectral -- specs/v1/openapi.yaml
   ```
3. Verify backward compatibility against the main branch schema.
4. Report contract violations or breaking field removals in structured markdown tables.

To ensure optimal context economics, keep the YAML description concise (under 200 characters) while embedding clear trigger words. During agent startup, Google Antigravity inspects only this header, consuming just 35 to 50 tokens. The complete procedural guide loads only when triggered, preventing context budget exhaustion across large repositories. To draft compliant frontmatter schemas automatically, use our free Claude Skill Creator.

Multi-Agent Delegation: Scoping Skills Across Parent Agents and Subagents

Google Antigravity allows agents to define and invoke subagents programmatically. This architecture introduces a powerful capability: dynamic skill scoping. Rather than provisioning every subagent with a monolithic skill library, a parent planner agent can define ephemeral subagents equipped with tailored tools and instructions.

When a parent agent calls define_subagent, it specifies:

• Name & Role: A unique identifier and job title (e.g., database-migration-verifier).
• Tool Grants: Explicit permission flags such as EnableWriteTools: false for read-only research subagents or EnableMCPTools: true for external database access.
• System Prompt: Specialized execution guidelines and domain heuristics that apply solely to that subagent.
• Workspace Scoping: Whether the subagent inherits the parent workspace or branches into a sandbox.

This multi-agent pattern adheres to the principle of least privilege. A code-review subagent can be granted read-only workspace access with custom review skills, while an infrastructure deployment agent receives explicit write capabilities. For engineering teams managing complex rule hierarchies, see our guide on resolving multi-agent instruction precedence conflicts.

Can You Synchronize Workspace Skills Across Laptops and Coding Assistants?

Yes, you can synchronize workspace skills across laptops and coding assistants by pairing Git repository tracking with a centralized skill manager. While committing .gemini/skills/ to Git handles project-level sharing for team members working in the same repository, personal workflow skills and multi-agent cross-tool setups require automated background synchronization.

Developers frequently transition between multiple AI coding assistants depending on their immediate task: Google Antigravity for autonomous multi-agent planning, Claude Code in the CLI for rapid single-file refactoring, Cursor in the IDE for inline tab-completion, and ChatGPT or Claude in the browser for architecture brainstorming. Managing disparate configuration formats across these surfaces creates severe administrative overhead.

Prompttly eliminates this fragmentation by acting as a single authoritative vault for all your agent instructions:

• Bidirectional Filesystem Sync: Prompttly maps your cloud skill library into local directories like ~/.gemini/antigravity/skills/, ~/.claude/skills/, and ~/.codex/skills/ automatically. Updates made in one tool reflect across all agents in real time.
• Sub-200ms Mac Hotkey Palette: Press a global keyboard shortcut anywhere on macOS to open a fuzzy-search palette and insert reusable prompts directly into any terminal, IDE, or browser chat without switching windows.
• Model Context Protocol (MCP) Server: Exposes your full instruction library over standardized MCP protocols, enabling Antigravity agents, Claude Desktop, and Cursor to read and query skills programmatically.

For complete category comparisons and tool evaluations, explore our comprehensive guide to the best AI skill managers for AI agents.

Related Resources and Next Steps

Expand your understanding of multi-agent instruction architecture by exploring the complete library on the Prompttly Resources Hub. Read our companion technical breakdowns:

• Google Antigravity Agent Skills: Architecture, Formats, and Portability
• Google Antigravity Rules: Configuring Workspace Scopes and Guidelines
• Google Antigravity Workflows vs Claude Code Subagents
• Google Antigravity vs Cursor Rules: How to Sync Guidelines Across Agents
• One Reusable Skill Library Across Claude Code, Codex, Cursor, and Antigravity

To stop losing skills across laptops and unify your prompts across Antigravity, Claude Code, and Cursor, check out Prompttly pricing or download the Prompttly Mac App.

Frequently Asked Questions