# What is ag-kit Used For? Complete Guide to the Antigravity AI Agent Engineering Kit

> Explore ag-kit, the Antigravity AI agent engineering kit. Build, debug, and deploy software projects safely with reusable agents and workflows on the Google Antigravity runtime.

- Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit)
- Tags: getting-started
- Published: 2026-07-29

---

**ag-kit is an Antigravity-first AI agent engineering kit that provisions a Markdown-driven workspace (`.agents/`) containing 20 reusable AI agents, 47 specialized skills, and 13 orchestration workflows designed to run on the Google Antigravity runtime for building, debugging, and deploying software projects safely.**

ag-kit, developed in the `vudovn/ag-kit` repository, transforms standard software projects into AI-native development environments. By initializing a structured `.agents/` directory within your codebase, it enables the Google Antigravity runtime to discover and orchestrate domain-specific AI personas that can write code, debug issues, and manage deployments through deterministic, safety-guarded workflows.

## Core Architecture of the ag-kit Workspace

The toolkit establishes a self-contained ecosystem within the `.agents/` directory, implementing a **managed component registry** that tracks every AI asset through dual-track versioning (CalVer for the toolkit, SemVer for individual components). This registry is maintained in [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) with locked dependencies in [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json), while [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) provides a visual representation of component relationships. According to [`.agents/ARCHITECTURE.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md), this structure ensures reproducible agent behavior across different environments and team members.

### Managed Component Inventory

The workspace organizes AI capabilities into five distinct categories:

- **Agents** (20 role-based personas including `frontend-specialist`, `backend-specialist`, and `orchestrator`)
- **Skills** (47 progressive knowledge modules such as `nextjs-react-expert`, `api-patterns`, and `vulnerability-scanner`)
- **Workflows** (13 slash-command procedures like `/brainstorm`, `/coordinate`, and `/orchestrate`)
- **Rules** (6 workspace-wide constraints governing routing, coding standards, and safety boundaries)
- **Memory** (Persistent project context storage under `.agents/memory/`)

## Antigravity Runtime Integration

The [`.agents/antigravity.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/antigravity.json) file declares a **runtime contract** that defines six integration phases: Discovery, MCP, Hooks, Orchestration, Plugin, and Validation. As detailed in [`AGENT_FLOW.md`](https://github.com/vudovn/ag-kit/blob/main/AGENT_FLOW.md), this contract allows the Antigravity runtime to load rules, activate skills, route requests to specialized agents, and execute tools within strictly enforced boundaries.

## Safety and Deterministic Execution

### The PreToolUse Safety Hook

A critical feature preventing destructive operations is the native **PreToolUse** hook registered in [`.agents/hooks.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks.json). Before any tool execution, the runtime invokes `node .agents/hooks/validate-tool-call.mjs` to analyze commands for high-confidence destructive patterns (such as `rm -rf /`). The hook implements a blocking mechanism that returns a non-zero exit code when dangerous operations are detected, effectively sandboxing agent actions.

```bash
printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' \
  | node .agents/hooks/validate-tool-call.mjs

# Expected output: BLOCKED by AG Kit (non-zero exit)

```

### Verification and Testing Scripts

The repository includes comprehensive verification scripts located in `.agents/scripts/`:

- [`generate_manifest.py`](https://github.com/vudovn/ag-kit/blob/main/generate_manifest.py): Validates component metadata and generates the deterministic registry
- [`dependency_graph.py`](https://github.com/vudovn/ag-kit/blob/main/dependency_graph.py): Produces visual dependency mappings
- [`verify_all.py`](https://github.com/vudovn/ag-kit/blob/main/verify_all.py): Executes full-stack validation including security scans, linting, type-checking, Lighthouse audits, and Playwright E2E tests

Developers can trigger these checks through npm scripts:

```bash
npm run check:agents      # Validate component registry

npm run check:antigravity # Run read-only diagnostics

npm run test:antigravity  # Execute the full test suite

```

## CLI Installation and Management

The `ag-kit` command-line tool handles workspace lifecycle management without requiring global installation.

### Initializing the Workspace

Install ag-kit into any existing project using npx:

```bash
npx @vudovn/ag-kit init

```

This command scaffolds the `.agents/` directory with all managed components, configuration files, and the Antigravity runtime contract.

### Safe Update Workflows

The CLI implements non-destructive update mechanisms:

```bash

# Preview changes without file modifications

ag-kit update --dry-run

# Apply updates with automatic backup creation

ag-kit update

# Restore previous state if issues occur

ag-kit rollback

```

Conflicts during updates are isolated in `.agents/.ag-kit/conflicts/` for manual review, ensuring production stability.

## Practical Agent Workflows

### Feature Development with Orchestration

To scaffold new functionality, invoke the `/orchestrate` slash command. This triggers the `orchestrator` agent to decompose requirements, assign specialist agents (frontend, backend, database), and generate implementation code using relevant skills from the registry.

### Systematic Debugging

For debugging tasks, the `/debug` command activates the `debugger` agent, which loads the `systematic-debugging` skill to analyze logs, trace failures, and propose fixes based on the project's memory context and established rules.

## Summary

- **ag-kit** provides a complete AI agent engineering environment through a Markdown-driven `.agents/` workspace compatible with the Google Antigravity runtime.
- The architecture centers on a **managed component registry** ([`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json)) that versions 20 agents, 47 skills, and 13 workflows for deterministic reproducibility.
- **Safety guarantees** come from the `PreToolUse` hook in `validate-tool-call.mjs`, which blocks destructive commands before execution.
- The **CLI tool** (`npx @vudovn/ag-kit init`) enables non-destructive installation and updates with automatic backup and conflict isolation.
- **Verification scripts** ([`verify_all.py`](https://github.com/vudovn/ag-kit/blob/main/verify_all.py), [`generate_manifest.py`](https://github.com/vudovn/ag-kit/blob/main/generate_manifest.py)) ensure workspace integrity through automated security scans, testing, and dependency graph generation.

## Frequently Asked Questions

### What is ag-kit used for in software development?

ag-kit transforms traditional codebases into AI-native development environments by establishing an `.agents/` workspace where specialized AI personas can write, debug, and deploy code. It is specifically designed for the Google Antigravity runtime, enabling automated orchestration of complex software tasks through slash commands like `/orchestrate` and `/debug` while maintaining safety through deterministic component registries and execution hooks.

### How does ag-kit prevent AI agents from executing dangerous commands?

The toolkit implements a **PreToolUse** safety hook defined in [`.agents/hooks.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks.json) that intercepts every tool call before execution. This hook runs `node .agents/hooks/validate-tool-call.mjs` to analyze commands for destructive patterns (such as `rm -rf /` or aggressive database drops). If the validator detects high-risk operations, it exits with a non-zero code, causing the Antigravity runtime to block the action and prevent potential system damage.

### Can ag-kit be integrated into existing projects without disrupting current workflows?

Yes. The ag-kit CLI installs all components into an isolated `.agents/` directory, leaving existing source code untouched. The `ag-kit update --dry-run` command allows teams to preview changes before applying them, and the automatic backup system with `ag-kit rollback` ensures that any problematic updates can be reversed instantly. The npm scripts (`check:agents`, `check:antigravity`) run read-only diagnostics that verify configuration without modifying project files.

### What types of AI agents and skills are included in the default ag-kit installation?

The default workspace includes **20 agents** covering roles such as `frontend-specialist`, `backend-specialist`, `devops-engineer`, and `orchestrator`. These agents draw from **47 skills** including `nextjs-react-expert`, `api-patterns`, `vulnerability-scanner`, and `systematic-debugging`. Additionally, **13 workflows** provide slash-command procedures for common operations like `/brainstorm` for strategic planning and `/coordinate` for multi-agent task management.