How to Build AG Kit: The Complete Build Process Explained

The AG Kit build process comprises three sequential stages: generating the component registry (including manifest files and dependency graphs), packaging the Antigravity-compatible plugin from the .agents/ directory, and compiling the Next.js documentation site, all orchestrated via npm scripts in the root package.json.

The AG Kit repository (vudovn/ag-kit) is a modular framework for AI agent development that requires a multi-step build pipeline to validate components, package distributions, and generate documentation. Understanding this build process is essential for contributors verifying changes or users creating custom agent configurations. The pipeline leverages both Python scripts for registry management and Node.js tooling for packaging and web builds.

The Three Core Build Stages

The build system separates concerns into distinct stages: registry generation, plugin packaging, and documentation building. Each stage produces specific artifacts required for the complete distribution.

1. Component Registry Generation

The registry stage validates and catalogs all agents, skills, workflows, and rules defined in the repository. According to the source code in .agents/scripts/generate_manifest.py, this process scans the .agents/ directory structure to produce machine-readable manifests.

Key commands:

# Generate manifest.json and manifest.lock.json

npm run generate:agents

# Validate registry integrity and dependency graphs

npm run check:agents

The generate:agents script executes generate_manifest.py to create the lock files, while check:agents runs both generate_manifest.py --check and dependency_graph.py --check to verify consistency and regenerate the Mermaid dependency diagram (DEPENDENCY_GRAPH.md).

2. Antigravity Plugin Packaging

This stage packages the entire .agents/ folder into a distributable Antigravity-compatible plugin format. The core logic resides in .agents/hooks/build-plugin.mjs, which handles the orchestration of agents, skills, rules, and workflows into the final plugin structure.

Build command:

npm run build:antigravity-plugin

This command outputs to dist/antigravity-plugin/, creating a self-contained package ready for deployment within the Antigravity ecosystem.

3. Web Documentation Site

The documentation portal is a Next.js application located in the web/ directory. The build process includes linting, TypeScript type checking, and static site generation configured via web/next.config.ts.

Command sequence:

npm run lint:web
npm run typecheck:web
npm run build:web

These scripts ensure code quality standards before producing the final static documentation assets.

Continuous Integration Workflow

The .github/workflows/ci.yml file defines the automated pipeline that runs on Ubuntu-latest runners. The CI orchestration strings all build stages together with additional validation steps:

1. Registry validation – Executes generate_manifest.py --check and dependency_graph.py --check to verify manifest integrity
2. Toolkit testing – Runs python -m unittest discover -s .agents/scripts/tests to validate Python utilities
3. Plugin build – Invokes npm run build:antigravity-plugin to create the distribution package
4. CLI testing – Executes npm test within the cli/ directory to verify command-line functionality
5. Web validation – Performs npm run lint, npm run typecheck, and npm run build inside web/

The workflow aborts on any failure, ensuring that successful CI runs represent fully built and verified AG Kit distributions.

Local Build Instructions

To replicate the complete CI pipeline locally, execute the following sequence from the repository root:

# Install dependencies

npm ci

# Run full build pipeline

npm run generate:agents && \
npm run check:agents && \
npm run build:antigravity-plugin && \
npm run lint:web && \
npm run typecheck:web && \
npm run build:web

Individual components can be built separately using the specific npm scripts defined in the root package.json (lines 28-39).

Key Build Configuration Files

The following files define and orchestrate the build process:

• package.json (root) – Defines top-level scripts: generate:agents, check:agents, build:antigravity-plugin, lint:web, typecheck:web, and build:web
• .agents/scripts/generate_manifest.py – Python script generating registry manifests
• .agents/scripts/dependency_graph.py – Generates Mermaid dependency visualizations
• .agents/hooks/build-plugin.mjs – Node.js script handling Antigravity plugin packaging
• .github/workflows/ci.yml – CI/CD orchestration configuration
• web/next.config.ts – Next.js build configuration for documentation
• cli/package.json – CLI package definitions and test scripts

Summary

• The AG Kit build process consists of registry generation, plugin packaging, and documentation building
• Registry commands (generate:agents, check:agents) produce manifest.json, manifest.lock.json, and DEPENDENCY_GRAPH.md via Python scripts
• Plugin building (build:antigravity-plugin) packages the .agents/ folder using .agents/hooks/build-plugin.mjs
• Web building requires three sequential commands: lint:web, typecheck:web, and build:web
• CI automation in .github/workflows/ci.yml runs validation, Python unit tests, plugin builds, CLI tests, and web builds on every commit

Frequently Asked Questions

What files are generated during the AG Kit build process?

The build produces manifest.json and manifest.lock.json in the repository root, DEPENDENCY_GRAPH.md containing Mermaid diagrams of component relationships, and the dist/antigravity-plugin/ directory containing the packaged plugin files. The web build generates static assets in the web/ directory's output folder.

How do I validate the component registry before committing changes?

Run npm run check:agents to execute both the manifest validation and dependency graph verification. This command runs generate_manifest.py --check and dependency_graph.py --check, which will exit with an error code if the registry state is inconsistent or if circular dependencies exist in the agent definitions.

What is the difference between generate:agents and check:agents?

The generate:agents command updates manifest.json and manifest.lock.json with the current state of the .agents/ directory, while check:agents validates the existing files without writing changes. In CI environments, check:agents ensures that committed manifests match the actual source code structure, preventing out-of-sync registry states.

Can I build the AG Kit components individually?

Yes. Each component uses independent npm scripts defined in the root package.json. You can run npm run build:antigravity-plugin to package only the plugin, or execute the web-specific commands (lint:web, typecheck:web, build:web) separately when working on documentation changes. The Python-based registry scripts can also be invoked directly using python .agents/scripts/generate_manifest.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}