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

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:

# 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 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, manifest.lock.json, or 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, 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.
2. Add front-matter containing name, description, and a SemVer version according to the schema defined in .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:

npm run generate:agents

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

npm run check:agents

The validation script invokes .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 and 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 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.

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 or 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 and 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. Git and a package manager (npm or pnpm) are also required.

Why can't I edit manifest.json directly?

The manifest.json and 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, and specific component schemas are defined in .agents/schemas/component-frontmatter.schema.json.

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