# How to Build AG Kit: The Complete Build Process Explained

> Discover the complete AG Kit build process. Learn how to generate the component registry, package plugins, and compile documentation through efficient npm scripts. Get started today.

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

---

**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`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/generate_manifest.py), this process scans the `.agents/` directory structure to produce machine-readable manifests.

**Key commands:**

```bash

# 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`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/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:**

```bash
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`](https://github.com/vudovn/ag-kit/blob/main/web/next.config.ts).

**Command sequence:**

```bash
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`](https://github.com/vudovn/ag-kit/blob/main/.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:

```bash

# 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`](https://github.com/vudovn/ag-kit/blob/main/package.json) (lines 28-39).

## Key Build Configuration Files

The following files define and orchestrate the build process:

- **[`package.json`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/generate_manifest.py)** – Python script generating registry manifests
- **[`.agents/scripts/dependency_graph.py`](https://github.com/vudovn/ag-kit/blob/main/.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`](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/ci.yml)** – CI/CD orchestration configuration
- **[`web/next.config.ts`](https://github.com/vudovn/ag-kit/blob/main/web/next.config.ts)** – Next.js build configuration for documentation
- **[`cli/package.json`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json), and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/.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`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) and [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json) in the repository root, [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) and [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/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`](https://github.com/vudovn/ag-kit/blob/main/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`.