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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
scope
dev
metadata
{"internal":true}
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:
Set brand tokens with the build-time theme configuration when tokens are
enough.
Register company components in app/design-system.ts with
defineDesignSystem, then pass that definition to ToolkitProvider.
Configure a public feature through its semantic components, headless
controller, and product-level render slots.
Compose app primitives behind the app's local UI adapter layer.
Eject the smallest feature into app-owned source.
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:
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 contract has nine leaf components (ActionButton, IconButton,
TextField, TextArea, Spinner, Skeleton, Status, Surface, Avatar)
and eight behavior components (Tooltip, Menu, Popover, Dialog,
Picker, Checkbox, Switch, Tabs). Picker covers select and combobox
behavior, not date picking. Behavior adapters own their portal, focus,
keyboard, dismissal, and stacking implementation while honoring the semantic
props and portalContainer interop contract.
App product code imports standard controls from its local adapter path, usually
@/components/ui/*. Do not import @agent-native/toolkit/ui/* directly from
pages, routes, or domain components. That bypasses the app seam and makes a
future design-system replacement incomplete. Toolkit feature packages remain
valid imports; configure their presentation through the registered semantic
components, controller, and product slots.
Run the published conformance kit against a complete adapter in its own CI:
New components and optional props are minor contract changes. Required props,
removed APIs, or behavioral changes require a new contract major.
Customize A Shared Feature
Prefer feature-level headless controllers over rebuilding individual widgets.
One controller must power both the Toolkit default view and every custom render
path so behavior, actions, analytics, accessibility state, and error handling
cannot drift. Use a product-level render slot to replace the view while keeping
that controller. Eject only when the controller and slots cannot express the
required product behavior.
Eject A Feature
Discover and inspect the ejection units published by installed first-party
packages before changing source:
The command is dry-run by default. It prints the file closure, consumer import
rewrites, protected package contracts, and verification commands before
writing. --apply copies the package-version-matched source into the app and
rewrites only imports covered by the unit manifest.
Every first-party public ejection unit must have a complete manifest. If one is
missing, treat that as a framework coverage bug instead of inventing a copy
recipe. For an unknown third-party package, use the emitted add-style blueprint
as a starting point. Protected runtime behavior is never copied; follow the
reported configuration, adapter, or extension seam instead.
Applied ejections are recorded in the committed
agent-native.ejections.json, including package version, manifest digest,
target hashes, and import rewrites. Use the recorded state to review drift or
undo an unchanged ejection:
Restore is hash-gated. It refuses to remove locally edited files or reverse
changed imports and prints their diff instead. Keep an edited ejection as
app-owned code, or reconcile those edits before restoring it.
Find The Installed Implementation
Use the source that matches the installed package version:
pnpm action docs-search --query "<component or feature>"
pnpm action source-search --query "<component or symbol>"
rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
Toolkit publishes readable TypeScript under
node_modules/@agent-native/toolkit/src/ for selective UI adoption.
First-party template source lives under
node_modules/@agent-native/core/corpus/templates/; Core's own implementation
lives under node_modules/@agent-native/core/dist/.
Treat those trees as read-only references. Prefer agent-native eject so the
package manifest selects the complete source closure and rewrites imports.
Manual inspection is still useful for deciding whether to configure,
compose, eject, or propose a shared seam.
Do not manually guess at sibling dependencies. The ejection manifest owns the
required file closure and keeps protected contracts on public package imports.
Preserve The Agent-Native Contract
UI ownership may change; product contracts should not:
Keep app operations in defineAction actions and call them through
useActionQuery, useActionMutation, or another named client helper.
Keep navigation, selection, and focused-object state visible through the
existing application-state keys.
Keep AI work in the shared agent chat instead of adding direct LLM calls.
Keep auth, access checks, persistence, chat transport, and agent execution in
Core. Do not copy those runtimes into the app.
Keep local adapters narrow so package upgrades still improve every surface
the app has not intentionally taken ownership of.
Keep page, route, and domain code on local UI adapter imports. Never reach
around the registered design system with direct Toolkit UI primitive imports.
App Shapes
Template app: begin with app/design-system.ts, its local UI adapters,
and domain UI. Use Toolkit features for repeated workspace behavior; eject
only the unit being customized.
Chat app: keep AgentChatSurface, thread state, and chat transport in
Core. Compose or eject Toolkit presentation such as chat-history UI around it.
Headless app: stay action-first while no UI is needed. When adding a UI,
use the Chat template as the on-ramp or add Toolkit components without
replacing the existing actions.
Workspace: put one-app overrides in that app. Promote a local component
to packages/shared only when multiple workspace apps use it.
After Ejecting
Commit agent-native.ejections.json with the app-owned files and rewrites.
Remove unused dependencies and imports from the ejected files.
Keep visible text in the app's localization catalogs.
Run the manifest verification commands plus the app's formatter, typecheck,
and focused tests.
Re-check the installed source during future package upgrades; the app-owned
ejection does not receive upstream fixes automatically. Use eject diff to
distinguish recorded output from subsequent local edits.
Don't
Don't edit or import from node_modules/@agent-native/*/src at runtime.
Don't add pnpm.overrides, patches, or resolutions for Agent Native packages.
Don't copy Core auth, DB, action, agent-loop, or transport internals.
Don't manually copy a first-party unit with a missing recipe; fix its manifest.
Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
Don't fork feature state into a custom view; consume the feature's controller.
Related Skills
agent-native-docs — version-matched docs and source lookup
