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

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 GitHub page.
2. Clone your fork locally:

   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:

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:

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:

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. Run these commands before committing:

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:

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 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 files require updates when features change

When modifying 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:

git checkout -b my-feature

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

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) 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) 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 explaining the specific use case. Ensure your template integrates with the core action system defined in 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 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. 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.

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