# How to Contribute to ag-kit: The Complete Guide for AI-Agent Developers

> Learn how to contribute to ag-kit with this complete guide. Follow steps to fork, install, modify, generate, validate, and submit your pull request for AI-agent development.

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

---

**To contribute to ag-kit, fork the repository, install Node ≥18 and Python ≥3.10, modify components in the `.agents/` directory, run `npm run generate:agents` to regenerate auto-generated manifests, validate your changes with `npm run check:agents`, and submit a pull request against the `main` branch.**

Contributing to ag-kit means working with a unique Antigravity-first AI-agent engineering kit that ships three distinct deliverables—a Markdown-based toolkit, an npm CLI package, and a Next.js documentation site—within a single repository. Whether you are adding new agent contracts, skills, or workflows to the toolkit or enhancing the `@vudovn/ag-kit` CLI, understanding the managed component workflow and manifest synchronization is essential for successful contributions to the `vudovn/ag-kit` project.

## Prerequisites

Before setting up your local development environment, ensure you have the following tools installed:

- **Git** – for forking and cloning the repository.
- **Node.js ≥18** – the CLI and documentation site use ESM modules.
- **Python ≥3.10** – required for running the toolkit validator scripts.
- **pnpm or npm** – for installing package dependencies across the monorepo.

## Setting Up the Local Development Environment

Start by forking the repository on GitHub, then clone your fork and install dependencies across the workspace:

```bash

# Clone your fork

git clone https://github.com/<YOUR-USERNAME>/ag-kit.git
cd ag-kit

# Install root-level dev dependencies

npm ci

# Install CLI and web sub-projects

cd cli && npm ci && cd ..
cd web && npm ci && cd ..

```

The root [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json) contains workspace scripts that orchestrate tasks across the entire repository. All subsequent commands should be run from the repository root unless specified otherwise.

## Understanding the Repository Structure

The `vudovn/ag-kit` repository organizes code into three distinct areas:

### The Toolkit (`.agents/`)

The **toolkit** contains managed components—agent contracts, skills, workflows, rules, memory schemas, and hooks—that the Antigravity runtime consumes as Markdown and JSON files. This is where most contributions occur.

**Critical rule:** Never edit [`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), or [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) directly. These files are auto-generated by the build scripts.

### The CLI (`cli/`)

The **CLI** is the npm package `@vudovn/ag-kit` that users install to sync the toolkit into their projects. Core logic resides in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js), which handles the synchronization between the repository and user projects via `giget`.

### The Documentation Site (`web/`)

The **docs site** is a Next.js portal that generates human-readable documentation from JSON catalogs. It sources content from the toolkit's structured data.

## Contributing to the Toolkit

The managed components in `.agents/` follow a strict generation workflow to maintain consistency across the registry.

### Adding New Agents, Skills, or Workflows

When creating new components, follow this exact sequence:

1. **Create the Markdown file** in the appropriate subdirectory, such as [`.agents/agent/my-new-agent.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/agent/my-new-agent.md).
2. **Add front-matter** containing `name`, `description`, and a SemVer `version` according to the schema defined in [`.agents/schemas/component-frontmatter.schema.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/schemas/component-frontmatter.schema.json).
3. **Declare dependencies** in the `tools` or `dependencies` sections of the front-matter if your component relies on other agents or skills.
4. **Run the generator** to update the registry:

```bash
npm run generate:agents

```

5. **Validate the component** to ensure it registers correctly and dependency graphs resolve:

```bash
npm run check:agents

```

The validation script invokes [`.agents/scripts/validate_kit.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/validate_kit.py), which checks front-matter versions, component dependencies, and overall graph integrity using Python's standard library only.

### Updating Existing Components

When modifying existing agents, skills, or workflows:

- Bump the component's `version` in the front-matter before committing.
- Run `npm run generate:agents` to refresh [`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).
- Execute `npm run check:agents` to verify no dependency conflicts were introduced.

### Working with Hooks

Hooks reside under `.agents/hooks/` and must obey the **PreToolUse** safety gate. When contributing hook logic, consult [`.agents/hooks/README.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/hooks/README.md) and the reference implementation in `.agents/hooks/validate-tool-call.mjs` to ensure compliance with the security model.

## Running Tests

The repository maintains three independent test suites that must pass before submitting a pull request:

| Suite | Command | Coverage |
|-------|---------|----------|
| **Toolkit** | `npm run test:toolkit` | Python unit tests under `.agents/scripts/tests` |
| **CLI** | `npm run test:cli` | Node tests in `cli/test/` |
| **Web** | `npm run lint:web && npm run typecheck:web && npm run build:web` | Lint, type-check, and build validation for the Next.js site |

All commands must exit successfully locally, as the same scripts run in CI via [`.github/workflows/ci.yml`](https://github.com/vudovn/ag-kit/blob/main/.github/workflows/ci.yml).

## Submitting a Pull Request

Follow this workflow to ensure your PR passes automated checks:

1. **Create a feature branch** on your fork: `git checkout -b feat/add-my-agent`.
2. **Make your changes** in `.agents/`, `cli/`, or `web/` as appropriate.
3. **Regenerate manifests** with `npm run generate:agents` if you touched any managed components.
4. **Run the full test suite** to verify toolkit integrity, CLI functionality, and web build stability.
5. **Commit** with a clear message referencing any relevant issue numbers.
6. **Push** to your fork and open a PR against `vudovn/ag-kit:main`.

The CI pipeline automatically validates that generated manifests are in sync with source files. If [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) or [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json) are out of date, the workflow will reject the PR until you re-run `npm run generate:agents` and commit the changes.

## Summary

- **Fork and clone** the `vudovn/ag-kit` repository and install Node ≥18 and Python ≥3.10.
- **Target the `.agents/` directory** for most contributions, but remember that [`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) are auto-generated—edit source Markdown files only.
- **Run `npm run generate:agents`** after any toolkit modification to synchronize the component registry.
- **Validate changes** with `npm run check:agents` and pass all three test suites (toolkit, CLI, and web) before submitting.
- **Submit PRs** against the `main` branch only after CI checks pass locally.

## Frequently Asked Questions

### What are the minimum version requirements to contribute to ag-kit?

You need Node.js version 18 or higher to support the ESM module format used in the CLI and web projects, and Python 3.10 or higher to run the validation scripts in [`.agents/scripts/validate_kit.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/scripts/validate_kit.py). Git and a package manager (npm or pnpm) are also required.

### Why can't I edit manifest.json directly?

The [`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) files are auto-generated artifacts that serve as the canonical registry for the Antigravity runtime. Editing them manually would create synchronization errors. Instead, modify the source Markdown files in `.agents/` and run `npm run generate:agents`, which invokes the Python generator to update these files deterministically.

### How do I validate my changes before submitting a pull request?

After making changes to managed components, run `npm run generate:agents` to update the manifests, then `npm run check:agents` to execute the Python validator. Additionally, run `npm run test:toolkit` for Python tests, `npm run test:cli` for Node tests, and the web linting and build commands to ensure full coverage.

### Where can I find detailed architecture documentation?

Comprehensive contributor guidance is available in **CLAUDE.md** at the repository root, which covers generation workflows, versioning strategies, and release safety. High-level architecture diagrams are documented in **[`.agents/ARCHITECTURE.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/ARCHITECTURE.md)**, and specific component schemas are defined in [`.agents/schemas/component-frontmatter.schema.json`](https://github.com/vudovn/ag-kit/blob/main/.agents/schemas/component-frontmatter.schema.json).