# How to Contribute to Agent-Native: A Complete Guide for Open Source Developers

> Learn how to contribute to Agent Native for open source development. Follow our guide to fork, install, code, test, and submit your pull request to the BuilderIO Agent Native repo.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-21

---

**To contribute to Agent-Native, fork the repository, install dependencies with pnpm, create a feature branch, run tests and linting, then submit a pull request against the main branch.**

Agent-Native is an open-source framework by BuilderIO that enables developers to build AI-powered applications using a unified action system. Whether you want to add new templates, fix bugs, improve documentation, or extend core functionality, this guide covers the complete workflow from setup to merge.

## Setting Up Your Development Environment

Before writing code, you need to configure your local environment to match the monorepo structure used by the BuilderIO/agent-native project.

### Forking and Cloning the Repository

Start by creating your own copy of the repository on GitHub.

1. Click **Fork** on the [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native) GitHub page.
2. Clone your fork locally:
   ```bash
   git clone https://github.com/<your-username>/agent-native.git
   cd agent-native
   ```

### Installing Dependencies with pnpm

The project uses a **pnpm workspace** to manage multiple packages. Install the package manager if needed, then install all dependencies:

```bash
npm i -g pnpm
pnpm install

```

This command installs dependencies across the entire workspace, including `packages/core/`, `packages/skills/`, and all templates under `templates/`.

## Running the Development Server and Tests

Agent-Native provides scripts to verify your changes work correctly before submission.

### Starting the Nitro Dev Server

Run the development server to see changes live in your browser:

```bash
pnpm dev

```

This starts the Nitro dev server and opens the UI, typically at `http://localhost:3000`. The dev server hot-reloads changes to templates and core code.

### Running the Vitest Test Suite

Ensure your changes don't break existing functionality by running the test suite:

```bash
pnpm test

```

Tests are located under `packages/**/src/**/*.spec.ts` and execute using **Vitest**. The test suite covers core actions, skill integrations, and template behaviors.

## Code Quality and Linting

Maintaining consistent code style is required for all contributions to Agent-Native.

### Prettier and ESLint Configuration

The repository enforces formatting rules defined in `.prettierrc` and linting rules in [`.oxlintrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxlintrc.json). Run these commands before committing:

```bash
pnpm lint      # Runs ESLint

pnpm format    # Runs Prettier

```

These checks run automatically in CI, so running them locally prevents review delays.

### Running Guard Scripts Locally

Before opening a pull request, execute the helper guard scripts to catch policy violations:

```bash
pnpm guard

```

These scripts (located in `scripts/guard-*.mjs`) detect common issues like unscoped queries, accidental environment variable exposure, or duplicate action routes. For example, `scripts/guard-no-env-credentials.mjs` prevents secrets from being committed to the repository.

## Making Your Contribution

Understanding the repository structure helps you place changes in the correct location.

### Understanding the Repository Structure

Agent-Native organizes code into distinct areas:

- **Core framework**: `packages/core/` contains the action system and [`defineAction.ts`](https://github.com/BuilderIO/agent-native/blob/main/defineAction.ts) helper
- **Templates**: `templates/` contains specific implementations (Calendar, Content, Slides, etc.)
- **Skills**: `packages/skills/` extends CLI functionality with specialized capabilities
- **Documentation**: `docs/` and individual [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) files require updates when features change

When modifying [`packages/core/src/defineAction.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/defineAction.ts), you are changing the central helper that creates actions used by the UI, agent, and CLI simultaneously.

### Creating a Feature Branch

Follow standard Git workflow to isolate your changes:

```bash
git checkout -b my-feature

```

Make your changes, then commit with a clear message describing what you added or fixed:

```bash
git add .
git commit -m "Add X feature / fix Y bug"
git push origin my-feature

```

**Important**: Never commit real credentials. If you need environment variables for local testing, add placeholder entries to `.env.example` instead of committing actual values.

### Submitting a Pull Request

Push your branch and open a Pull Request against the `main` branch of the upstream repository.

- The PR triggers **CI** (configured in [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml)) which runs lint, type-checking, and the full test suite
- Reviewers check against the **four-area checklist** (actions, UI, skills, data) described in `packages/core/src/templates/workspace-core/.agents/skills/`
- Address reviewer comments by pushing additional commits to your branch

Once merged, the automatic release workflow ([`auto-publish.yml`](https://github.com/BuilderIO/agent-native/blob/main/auto-publish.yml)) publishes a new package version, making your changes available in the next template release.

## Summary

- **Fork and clone** the BuilderIO/agent-native repository to your GitHub account
- **Install dependencies** using `pnpm install` to set up the workspace environment
- **Use `pnpm dev`** to start the Nitro development server and test changes live
- **Run `pnpm test` and `pnpm lint`** before submitting to ensure code quality
- **Execute `pnpm guard`** to catch policy violations like credential exposure
- **Place code correctly**: Core logic in `packages/core/`, templates in `templates/`, skills in `packages/skills/`
- **Submit PRs against `main`** and iterate based on reviewer feedback and CI results

## Frequently Asked Questions

### What is the four-area checklist mentioned in the contribution guidelines?

The four-area checklist is a review framework covering **actions**, **UI**, **skills**, and **data**. When you contribute to Agent-Native, reviewers verify that changes properly integrate across these four domains. This pattern is documented in the skill files under `packages/core/src/templates/workspace-core/.agents/skills/`, ensuring that any new action works consistently across the CLI, user interface, and agent runtime.

### How do I add a new template to Agent-Native?

Create a new directory under `templates/` following the structure of existing templates like Calendar or Content. Each template requires its own [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) explaining the specific use case. Ensure your template integrates with the core action system defined in [`packages/core/src/defineAction.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/defineAction.ts) and passes the test suite when running `pnpm test`.

### Why does my pull request fail CI checks?

CI failures typically result from three common issues: linting errors (run `pnpm lint` to fix), failing tests (run `pnpm test` to verify), or policy violations caught by the guard scripts (run `pnpm guard` locally). The CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml) enforces these standards to maintain code quality across the pnpm workspace.

### Can I use npm or yarn instead of pnpm?

No, Agent-Native requires **pnpm** because the repository uses a pnpm workspace configuration defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml). This file declares all packages including `core`, `skills`, and individual templates. Using npm or yarn will not correctly link the workspace dependencies, causing import errors when running `pnpm dev` or `pnpm test`.