# Customizing Agent Native

How to configure, compose, or eject Agent-Native features into app-owned code.

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill customizing-agent-native -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill customizing-agent-native -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill customizing-agent-native -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill customizing-agent-native -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

How to configure, compose, or eject Agent-Native features into app-owned code. Use when overriding shared components or integrations, customizing a template, adding UI to chat or headless apps, or inspecting package source.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Customizing Agent-Native

## Rule

Start with the app's registered design system and local UI adapters, then use
the public feature's props, semantic components, controller, product slots,
and callbacks. If those seams are not enough, use the eject CLI to transfer
the smallest supported feature into the app and make that copy app-owned.
Never edit `node_modules`, deep-import a private source file at runtime, or
patch an `@agent-native/*` package.

Use this order:

1. Set brand tokens with the build-time theme configuration when tokens are
   enough.
2. Register company components in `app/design-system.ts` with
   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
3. Configure a public feature through its semantic components, headless
   controller, and product-level render slots.
4. Compose app primitives behind the app's local UI adapter layer.
5. Eject the smallest feature into app-owned source.
6. Propose a new Toolkit seam when the same override is useful in two apps.

Ejection is for intentional product customization, not for hiding an upgrade
failure or replacing Core runtime behavior.

## Use A Company Design System

Keep the explicit, typed registration seam in `app/design-system.ts`:

```tsx
import { defineDesignSystem } from "@agent-native/toolkit/design-system";
import {
  AcmeActionButtonAdapter,
  AcmeDialogAdapter,
} from "./design-system/acme-adapter";

export const designSystem = defineDesignSystem({
  name: "Acme",
  components: {
    ActionButton: AcmeActionButtonAdapter,
    Dialog: AcmeDialogAdapter,
  },
});
```

Adapters translate the semantic Toolkit contract into company component props.
They are ordinary React components and may use MUI-style providers, React Aria,
CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
optional interoperability hooks, not Tailwind or CVA requirements.

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/customizing-agent-native/SKILL.md