Agent-Native Toolkit
Use this skill when deciding whether app chrome, settings, collaboration,
sharing, navigation, organization, setup, history, comments, or agent UX should
be built app-locally or moved into reusable framework/toolkit pieces.
Core Rule
Apps own domain models, domain actions, and product-specific workflows. The
framework and @agent-native/toolkit own repeated workspace behavior users
expect to work the same everywhere.
Move behavior into shared toolkit primitives when it is:
- workspace-wide, such as settings, nav, search, org membership, or setup
- agent-visible, such as context, actions, run progress, or proof-of-done
- governed, such as secrets, permissions, sharing, audit, or billing
- repeated by two or more apps
- not tied to one domain model
Keep behavior app-local when the abstraction would hide important domain
language or make a simple app-specific workflow harder to understand.
Agent Surface Contract
When using the shared app shell, keep its two navigation surfaces distinct:
- The left rail owns domain destinations and chat history when the app has a
full-page chat route. Do not label a domain workflow as
Chat just because
the app was scaffolded from the chat template.
- Settings is not a rail item. It opens from the account menu (
OrgSwitcher
in the sidebar footer) and from ⌘, (Ctrl+, elsewhere), which AppProviders
binds. Keep the /settings route; don't add a Settings entry to items,
secondaryItems, or the footer.
- The right
AgentSidebar owns contextual agent work. Domain buttons that call
sendToAgentChat should open it (openSidebar: true) so the user can see,
steer, and review the agent without losing the page they were using.
- Keep
/ or /chat/* as the full-page chat surface when the starter provides
one. Put domain workflows on named routes and wire the shell's route checks,
navigation labels, and handoffs to those routes together.
- Use familiar message or neutral action icons for agent affordances. Never use
sparkle, wand, magic, or robot icons as an AI label; the copy should carry the
meaning.
- Give the right rail a quiet visual boundary with a subtle surface shift,
divider, or both. The domain page and AgentSidebar should not collapse into a
single undifferentiated background.
- Any button labeled as agent work must use
sendToAgentChat with bounded
context and openSidebar: true; local deterministic analysis should be
labeled as local, preview, or analyze. For original/generated review, stack
the source above the result by default and use side-by-side only for short,
highly scannable content.
- Deterministic implementation does not make an AI-shaped experience
deterministic. If the user expects research, analysis, generation,
recommendation, synthesis, visible progress, or steering, route the button
to the AgentSidebar and let the agent call focused actions. Keep revisions in
the same thread instead of adding a second freeform prompt box.
- Standalone apps with
AgentSidebar must use one AgentKit controller and
transport. Core's AssistantChat export remains supported as an alias for
AgentKitAssistantChat; use AgentKit slots and registries for custom message
UI. Keep assistant-ui transcript/runtime imports inside the shared composer
integration; when linked dependencies need Vite aliases, resolve one
@agent-native/agentkit context and verify a real handoff.
Contextual agent UI is not a reason to expose every option at once. Start with
the domain task's primary action, reveal review or configuration only when the
current state needs it, and let the sidebar carry conversational depth.
When an app exposes context sources or integration shortcuts, show only
capabilities available to that app and the current caller. Keep retrieving
context distinct from asking the agent to invoke an integration, and recheck
availability when the user submits. Do not infer agent-tool access from a
connected messaging account or expose credential values. Link to shared
Integrations settings when a required connection is missing.
Visual Direction And Workspace Variety
Shared workspace behavior should be consistent without forcing every app into
the same visual skin. Keep shell and component tokens semantic, then let each
app record a visual direction in DESIGN.md before styling. Choose its palette
and composition from the product context, and keep semantic states accessible.
Do not make warm beige plus terracotta the workspace fallback. Preserve a
workspace-level brand when one exists; otherwise keep shared chrome neutral and
allow app-owned accents to distinguish products while retaining accessible
semantic states and the shared AgentSidebar contract.
Discover Before Building
Before creating an app-local version of repeated workspace or agent UI:
- Check the reusable kits below and the installed package documentation.
- Search installed public components and source with
docs-search and
source-search.
- Run
agent-native eject --list to see the version-matched units published
by the packages installed in this app.
- Read
customizing-agent-native and configure, compose, or eject the
smallest unit instead of recreating shared behavior from memory.
Use public package exports at runtime. Published source and ejection manifests
are discovery and ownership-transfer mechanisms, not private runtime APIs.
Design-System Boundary
For apps with a UI, keep an explicit design-system seam in
app/design-system.ts using defineDesignSystem from
@agent-native/toolkit/design-system, and supply it to ToolkitProvider. The
semantic contract contains:
- nine leaf components:
ActionButton, IconButton, TextField, TextArea,
Spinner, Skeleton, Status, Surface, and Avatar
- eight behavior components:
Tooltip, Menu, Popover, Dialog, Picker,
Checkbox, Switch, and Tabs
These are semantic contracts, not styling contracts. An adapter may use
Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
or another React design system. Do not assume CVA, utility classes, or even a
className; behavior adapters may supply their overlay and focus
implementation wholesale while honoring portal, focus-restoration, keyboard,
dismissal, ARIA, and z-index interoperability.
Pages, routes, and domain components import ordinary controls through the app's
local adapter layer, usually @/components/ui/*. They must not import
@agent-native/toolkit/ui/* directly. Toolkit feature exports are still the
right home for shared workspace behavior; their presentation flows through the
registered semantic components, feature controller, and product-level slots.
Import any design-system adapter explicitly; do not auto-detect it or load React
components from JSON. Run a custom adapter against
@agent-native/toolkit/conformance in the app's CI before adopting it.
Settings Direction
Durable settings belong in Settings. The agent sidebar should not become a
second settings app; it can show contextual quick controls and deep links.
Settings has the same groups in every app, and page ids are stable URL segments
(/settings/<page>/<sub>):
- Account:
profile, preferences, security
- Connections:
integrations (integrations/builder), api-keys
- Agent:
model, instructions, memory, skills, files, sub-agents
- Organization:
org, members, usage, and for owners and admins auth,
apps, infra, audit
- The app's group:
app (areas at app/<id>), notifications,
automations, channels (channels/<platform>), mcp, creative-context
- Footer:
labs, whats-new
Link with buildSettingsRoute(page, sub?, { anchor? }); older tab and section
ids continue to resolve through framework redirects. Account › Profile is the
canonical profile surface (get-user-profile, update-user-profile); don't
build an app-local profile page. Read the toolkit-settings documentation for
the current route and page ids.
When adding a new API key, OAuth grant, provider connection, model selector, app
preference, notification preference, or usage/billing surface, find the page
that owns that kind of setting first: provider keys go through the one provider
dialog on Model, other keys on API keys, channels on Channels, and app-only
preferences in the app's group. Only add sidebar UI when it is needed in the
moment of agent use.
The app's group in Settings
Settings has a group named after the app.
Core owns its pages: General, Notifications, Automations, Channels, MCP server,
Creative context, plus Labs and What's new in the footer. A template supplies
only its own content, through these SettingsTabsPage props:
generalGroups: the app's own SettingsGroups on its General page. Core puts
Agent › Default model above them (owners and admins change it; the agent
uses manage-agent-engine set-app-default) and This browser › Demo mode
below. Until a template passes it, today's general shows there.
appAreas: [{ id, label, content, visible?, keywords?, searchEntries? }],
tabs on the General page routed /settings/app/<id>. Set visible: false
while the lab behind an area is off. A tab with
settingsPlacement: "app-area" in extraTabs works the same.
notifications (plus notificationsSearchEntries): the Notifications page
shows only when this is passed.
mcpAbout: the MCP server page's about line, naming what an MCP host can do
in this app.
- Labs come from
labs; What's new comes from whatsNewMarkdown, or from the
ChangelogSettingsCard passed as whatsNew.
- Any other
extraTabs item becomes its own page in the app's group. To swap a
core page for a variant, registerSettingsPages([{ ...corePage, component }])
at module scope (Dispatch's Members keeps its app-role column this way). To
add a group to one channel's page, registerChannelSettingsExtensions.
The route needs a settings.$.tsx splat next to settings.tsx, and the layout
hides its own sidebar and header on Settings routes while the flag is on or
loading (isSettingsPathname), because the shell brings its own.
Search entries per area: each searchEntries item's hash is the row's
SettingsRow id, and a hit opens that area's tab and scrolls to the row. With
the flag off, the same props render as today's tabs, so a migrated template
works either way. Link with buildSettingsRoute("app", "<area>"), never a
hand-written path.
Gate UI on a lab with useLab(LAB_DEFINITION) rather than useLab(key): a
definition reads as its defaultEnabled until the server answers, while a bare
key reads as on.
Integration Setup Preflight
Before building any setup, settings, credential, OAuth, or connection surface,
search the workspace/provider connection catalog first. If the provider already
has a reusable connection, use its catalog, app grant, and scoped credential
resolver rather than registering a parallel secret. Only then classify fields
that still need app-local setup by lifecycle and scope:
| Need |
Default primitive |
| Deploy- or app-level configuration |
Runtime configuration or deployment env vars |
| Existing workspace/provider connection |
Workspace-connection catalog/grant plus resolveWorkspaceConnectionCredential(s)ForApp |
| App-local API/service key with no reusable connection |
registerRequiredSecret({ kind: "api-key" }) and the vault |
| Authorization-code or refresh-token flow |
kind: "oauth" with @agent-native/core/oauth-tokens |
| Account, customer, or other non-secret identifiers |
Scoped connection metadata or app data |
| Provider-specific prerequisites, sequencing, or health |
A thin app-local guide over the shared primitives |
Do not register every provider field as a generic secret, mark every field as
required, or create a second credential-management surface. One logical
connection should normally produce one onboarding outcome. A custom setup page
is appropriate only when it adds domain-specific guidance or readiness checks;
it should link to or call the shared settings, OAuth, and action surfaces rather
than duplicating their storage or transport.
Reusable Kits
- Settings kit: one searchable Settings page with Account, Connections,
Agent, and Organization groups plus a group for the app's own settings. The
index is built from page declarations; give every row a search entry whose
anchor is its
SettingsRow id so users find settings by name.
- Collaboration kit: Yjs docs, presence, agent presence, live cursors,
remote selections, recent edit highlights, real-time sync indicators, and
undo/redo grouping.
- Sharing kit: private/workspace/org/public-link access, invites, roles,
expirations, agent-readable links, and resource registration.
- Navigation and command kit: app shell, side nav, breadcrumbs, app switcher,
command palette entries, recent resources, pinned resources, and global search.
- Organization kit: folders, tags, favorites, archive, trash, ownership,
membership, and common resource metadata.
- Setup and connections kit: declarative setup requirements, model readiness,
missing-secret states, OAuth grants, and provider connection health.
- Agent UX kit: sidebar, composer, staged context, mentions, voice, human
approval, generative UI, progress, and screen-state exposure.
- Custom block kit: optional, sandboxed extensions for one-off behavior or
views. Apps opt in; Core owns sandboxing, storage, and access checks, while
Toolkit provides reusable adoption UI. Promote repeated or durable workflows
to app-owned actions and UI.
- Chat history kit: presentational chat lists and recent-chat rails belong
in Toolkit; Core keeps thread persistence, agent execution, transport, and
page-to-sidebar handoff. Apps provide routing, labels, and domain actions.
- Data grid kit: provider-agnostic spreadsheet mechanics belong in
@agent-native/toolkit/data-grid. Apps provide rows, typed columns, editor
slots, selection and width state, persistence callbacks, and product-level
row/body slots. Keep database models, access checks, grouping, drag/drop,
and domain actions in the app adapter.
- Agent page kit: the full-page Agent surface (
AgentTabsPage from
@agent-native/toolkit/app/agent-page) for agent resources, context
snapshots, integrations, automations, settings, and MCP access. The page
supports app-provided tabs. Use agent-native-docs to find current guidance
before adding it.
- History and recovery kit: audit log, activity feed, version history,
checkpoints, undo, redo, restore, and proof-of-done.
- Comments and review kit: anchored comments, pins, mentions, review
requests, resolved threads, agent follow-up tasks, and notifications.
- Workflow and observability kit: notifications, approvals, scheduled work,
background runs, recurring jobs, traces, evals, feedback, and run timelines.
Implementation Checklist
When adding or refactoring one of these areas:
- Search app code and installed package documentation/source for an existing
feature before building an app-local version.
- Configure the public feature through its data, action, controller, semantic
component, and product-level render seams.
- Keep shared data provider-agnostic and scoped by auth/sharing rules.
- Expose the same capability to the UI and agent through actions or documented
client helpers.
- Keep app-specific labels, routes, resource adapters, and settings panels in
the app integration instead of forking shared UI for one app.
- Document app-specific configuration for the next contributor; use
agent-native-docs when the installed package behavior is unclear.
- Prefer public props and slots; if they cannot express the need, use the
smallest supported ejection unit. See
customizing-agent-native for the
configure → compose → eject → propose seam ladder.
- Keep one controller as the source of truth for the default and custom render
paths. A custom design must not fork actions, analytics, async state, or
accessibility behavior.
- If the app registers a custom adapter, verify it with the conformance kit,
including focus, keyboard, dismissal, and portal behavior where components
meet framework surfaces.
Related Skills
Read these alongside this skill when the work touches the specific area:
sharing
secrets
adding-a-feature
agent-native-docs
Use agent-native-docs to find installed-version guidance for navigation,
screen context, collaboration, visual direction, and other capabilities not
included in your scaffold's skill set.
1---2name: agent-native-toolkit3description: >-4 Inventory and ownership rules for shared Agent-Native workspace UI. Use5 before building app chrome, settings, navigation, sharing, collaboration,6 setup, history, comments, chat rails, agent UX, or repeated workspace behavior.7scope: dev8metadata:9 source: https://skillmd.com/skills/builderio/agent-native-toolkit10 internal: true11---1213# Agent-Native Toolkit1415Use this skill when deciding whether app chrome, settings, collaboration,16sharing, navigation, organization, setup, history, comments, or agent UX should17be built app-locally or moved into reusable framework/toolkit pieces.1819## Core Rule2021Apps own domain models, domain actions, and product-specific workflows. The22framework and `@agent-native/toolkit` own repeated workspace behavior users23expect to work the same everywhere.2425Move behavior into shared toolkit primitives when it is:2627- workspace-wide, such as settings, nav, search, org membership, or setup28- agent-visible, such as context, actions, run progress, or proof-of-done29- governed, such as secrets, permissions, sharing, audit, or billing30- repeated by two or more apps31- not tied to one domain model3233Keep behavior app-local when the abstraction would hide important domain34language or make a simple app-specific workflow harder to understand.3536## Agent Surface Contract3738When using the shared app shell, keep its two navigation surfaces distinct:3940- The left rail owns domain destinations and chat history when the app has a41 full-page chat route. Do not label a domain workflow as `Chat` just because42 the app was scaffolded from the chat template.43- Settings is not a rail item. It opens from the account menu (`OrgSwitcher`44 in the sidebar footer) and from ⌘, (Ctrl+, elsewhere), which `AppProviders`45 binds. Keep the `/settings` route; don't add a Settings entry to `items`,46 `secondaryItems`, or the footer.47- The right `AgentSidebar` owns contextual agent work. Domain buttons that call48 `sendToAgentChat` should open it (`openSidebar: true`) so the user can see,49 steer, and review the agent without losing the page they were using.50- Keep `/` or `/chat/*` as the full-page chat surface when the starter provides51 one. Put domain workflows on named routes and wire the shell's route checks,52 navigation labels, and handoffs to those routes together.53- Use familiar message or neutral action icons for agent affordances. Never use54 sparkle, wand, magic, or robot icons as an AI label; the copy should carry the55 meaning.56- Give the right rail a quiet visual boundary with a subtle surface shift,57 divider, or both. The domain page and AgentSidebar should not collapse into a58 single undifferentiated background.59- Any button labeled as agent work must use `sendToAgentChat` with bounded60 context and `openSidebar: true`; local deterministic analysis should be61 labeled as local, preview, or analyze. For original/generated review, stack62 the source above the result by default and use side-by-side only for short,63 highly scannable content.64- Deterministic implementation does not make an AI-shaped experience65 deterministic. If the user expects research, analysis, generation,66 recommendation, synthesis, visible progress, or steering, route the button67 to the AgentSidebar and let the agent call focused actions. Keep revisions in68 the same thread instead of adding a second freeform prompt box.69- Standalone apps with `AgentSidebar` must use one AgentKit controller and70 transport. Core's `AssistantChat` export remains supported as an alias for71 `AgentKitAssistantChat`; use AgentKit slots and registries for custom message72 UI. Keep assistant-ui transcript/runtime imports inside the shared composer73 integration; when linked dependencies need Vite aliases, resolve one74 `@agent-native/agentkit` context and verify a real handoff.7576Contextual agent UI is not a reason to expose every option at once. Start with77the domain task's primary action, reveal review or configuration only when the78current state needs it, and let the sidebar carry conversational depth.7980When an app exposes context sources or integration shortcuts, show only81capabilities available to that app and the current caller. Keep retrieving82context distinct from asking the agent to invoke an integration, and recheck83availability when the user submits. Do not infer agent-tool access from a84connected messaging account or expose credential values. Link to shared85Integrations settings when a required connection is missing.8687## Visual Direction And Workspace Variety8889Shared workspace behavior should be consistent without forcing every app into90the same visual skin. Keep shell and component tokens semantic, then let each91app record a visual direction in `DESIGN.md` before styling. Choose its palette92and composition from the product context, and keep semantic states accessible.9394Do not make warm beige plus terracotta the workspace fallback. Preserve a95workspace-level brand when one exists; otherwise keep shared chrome neutral and96allow app-owned accents to distinguish products while retaining accessible97semantic states and the shared AgentSidebar contract.9899## Discover Before Building100101Before creating an app-local version of repeated workspace or agent UI:1021031. Check the reusable kits below and the installed package documentation.1042. Search installed public components and source with `docs-search` and105 `source-search`.1063. Run `agent-native eject --list` to see the version-matched units published107 by the packages installed in this app.1084. Read `customizing-agent-native` and configure, compose, or eject the109 smallest unit instead of recreating shared behavior from memory.110111Use public package exports at runtime. Published source and ejection manifests112are discovery and ownership-transfer mechanisms, not private runtime APIs.113114## Design-System Boundary115116For apps with a UI, keep an explicit design-system seam in117`app/design-system.ts` using `defineDesignSystem` from118`@agent-native/toolkit/design-system`, and supply it to `ToolkitProvider`. The119semantic contract contains:120121- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,122 `Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`123- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,124 `Checkbox`, `Switch`, and `Tabs`125126These are semantic contracts, not styling contracts. An adapter may use127Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,128or another React design system. Do not assume CVA, utility classes, or even a129`className`; behavior adapters may supply their overlay and focus130implementation wholesale while honoring portal, focus-restoration, keyboard,131dismissal, ARIA, and z-index interoperability.132133Pages, routes, and domain components import ordinary controls through the app's134local adapter layer, usually `@/components/ui/*`. They must not import135`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the136right home for shared workspace behavior; their presentation flows through the137registered semantic components, feature controller, and product-level slots.138139Import any design-system adapter explicitly; do not auto-detect it or load React140components from JSON. Run a custom adapter against141`@agent-native/toolkit/conformance` in the app's CI before adopting it.142143## Settings Direction144145Durable settings belong in Settings. The agent sidebar should not become a146second settings app; it can show contextual quick controls and deep links.147Settings has the same groups in every app, and page ids are stable URL segments148(`/settings/<page>/<sub>`):149150- Account: `profile`, `preferences`, `security`151- Connections: `integrations` (`integrations/builder`), `api-keys`152- Agent: `model`, `instructions`, `memory`, `skills`, `files`, `sub-agents`153- Organization: `org`, `members`, `usage`, and for owners and admins `auth`,154 `apps`, `infra`, `audit`155- The app's group: `app` (areas at `app/<id>`), `notifications`,156 `automations`, `channels` (`channels/<platform>`), `mcp`, `creative-context`157- Footer: `labs`, `whats-new`158159Link with `buildSettingsRoute(page, sub?, { anchor? })`; older tab and section160ids continue to resolve through framework redirects. Account › Profile is the161canonical profile surface (`get-user-profile`, `update-user-profile`); don't162build an app-local profile page. Read the `toolkit-settings` documentation for163the current route and page ids.164165When adding a new API key, OAuth grant, provider connection, model selector, app166preference, notification preference, or usage/billing surface, find the page167that owns that kind of setting first: provider keys go through the one provider168dialog on Model, other keys on API keys, channels on Channels, and app-only169preferences in the app's group. Only add sidebar UI when it is needed in the170moment of agent use.171172### The app's group in Settings173174Settings has a group named after the app.175Core owns its pages: General, Notifications, Automations, Channels, MCP server,176Creative context, plus Labs and What's new in the footer. A template supplies177only its own content, through these `SettingsTabsPage` props:178179- `generalGroups`: the app's own `SettingsGroup`s on its General page. Core puts180 Agent › Default model above them (owners and admins change it; the agent181 uses `manage-agent-engine` `set-app-default`) and This browser › Demo mode182 below. Until a template passes it, today's `general` shows there.183- `appAreas`: `[{ id, label, content, visible?, keywords?, searchEntries? }]`,184 tabs on the General page routed `/settings/app/<id>`. Set `visible: false`185 while the lab behind an area is off. A tab with186 `settingsPlacement: "app-area"` in `extraTabs` works the same.187- `notifications` (plus `notificationsSearchEntries`): the Notifications page188 shows only when this is passed.189- `mcpAbout`: the MCP server page's about line, naming what an MCP host can do190 in this app.191- Labs come from `labs`; What's new comes from `whatsNewMarkdown`, or from the192 `ChangelogSettingsCard` passed as `whatsNew`.193- Any other `extraTabs` item becomes its own page in the app's group. To swap a194 core page for a variant, `registerSettingsPages([{ ...corePage, component }])`195 at module scope (Dispatch's Members keeps its app-role column this way). To196 add a group to one channel's page, `registerChannelSettingsExtensions`.197198The route needs a `settings.$.tsx` splat next to `settings.tsx`, and the layout199hides its own sidebar and header on Settings routes while the flag is on or200loading (`isSettingsPathname`), because the shell brings its own.201202Search entries per area: each `searchEntries` item's `hash` is the row's203`SettingsRow` id, and a hit opens that area's tab and scrolls to the row. With204the flag off, the same props render as today's tabs, so a migrated template205works either way. Link with `buildSettingsRoute("app", "<area>")`, never a206hand-written path.207208Gate UI on a lab with `useLab(LAB_DEFINITION)` rather than `useLab(key)`: a209definition reads as its `defaultEnabled` until the server answers, while a bare210key reads as on.211212## Integration Setup Preflight213214Before building any setup, settings, credential, OAuth, or connection surface,215search the workspace/provider connection catalog first. If the provider already216has a reusable connection, use its catalog, app grant, and scoped credential217resolver rather than registering a parallel secret. Only then classify fields218that still need app-local setup by lifecycle and scope:219220| Need | Default primitive |221| --- | --- |222| Deploy- or app-level configuration | Runtime configuration or deployment env vars |223| Existing workspace/provider connection | Workspace-connection catalog/grant plus `resolveWorkspaceConnectionCredential(s)ForApp` |224| App-local API/service key with no reusable connection | `registerRequiredSecret({ kind: "api-key" })` and the vault |225| Authorization-code or refresh-token flow | `kind: "oauth"` with `@agent-native/core/oauth-tokens` |226| Account, customer, or other non-secret identifiers | Scoped connection metadata or app data |227| Provider-specific prerequisites, sequencing, or health | A thin app-local guide over the shared primitives |228229Do not register every provider field as a generic secret, mark every field as230required, or create a second credential-management surface. One logical231connection should normally produce one onboarding outcome. A custom setup page232is appropriate only when it adds domain-specific guidance or readiness checks;233it should link to or call the shared settings, OAuth, and action surfaces rather234than duplicating their storage or transport.235236## Reusable Kits237238- **Settings kit**: one searchable Settings page with Account, Connections,239 Agent, and Organization groups plus a group for the app's own settings. The240 index is built from page declarations; give every row a search entry whose241 anchor is its `SettingsRow` id so users find settings by name.242- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,243 remote selections, recent edit highlights, real-time sync indicators, and244 undo/redo grouping.245- **Sharing kit**: private/workspace/org/public-link access, invites, roles,246 expirations, agent-readable links, and resource registration.247- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,248 command palette entries, recent resources, pinned resources, and global search.249- **Organization kit**: folders, tags, favorites, archive, trash, ownership,250 membership, and common resource metadata.251- **Setup and connections kit**: declarative setup requirements, model readiness,252 missing-secret states, OAuth grants, and provider connection health.253- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human254 approval, generative UI, progress, and screen-state exposure.255- **Custom block kit**: optional, sandboxed extensions for one-off behavior or256 views. Apps opt in; Core owns sandboxing, storage, and access checks, while257 Toolkit provides reusable adoption UI. Promote repeated or durable workflows258 to app-owned actions and UI.259- **Chat history kit**: presentational chat lists and recent-chat rails belong260 in Toolkit; Core keeps thread persistence, agent execution, transport, and261 page-to-sidebar handoff. Apps provide routing, labels, and domain actions.262- **Data grid kit**: provider-agnostic spreadsheet mechanics belong in263 `@agent-native/toolkit/data-grid`. Apps provide rows, typed columns, editor264 slots, selection and width state, persistence callbacks, and product-level265 row/body slots. Keep database models, access checks, grouping, drag/drop,266 and domain actions in the app adapter.267- **Agent page kit**: the full-page Agent surface (`AgentTabsPage` from268 `@agent-native/toolkit/app/agent-page`) for agent resources, context269 snapshots, integrations, automations, settings, and MCP access. The page270 supports app-provided tabs. Use `agent-native-docs` to find current guidance271 before adding it.272- **History and recovery kit**: audit log, activity feed, version history,273 checkpoints, undo, redo, restore, and proof-of-done.274- **Comments and review kit**: anchored comments, pins, mentions, review275 requests, resolved threads, agent follow-up tasks, and notifications.276- **Workflow and observability kit**: notifications, approvals, scheduled work,277 background runs, recurring jobs, traces, evals, feedback, and run timelines.278279## Implementation Checklist280281When adding or refactoring one of these areas:2822831. Search app code and installed package documentation/source for an existing284 feature before building an app-local version.2852. Configure the public feature through its data, action, controller, semantic286 component, and product-level render seams.2873. Keep shared data provider-agnostic and scoped by auth/sharing rules.2884. Expose the same capability to the UI and agent through actions or documented289 client helpers.2905. Keep app-specific labels, routes, resource adapters, and settings panels in291 the app integration instead of forking shared UI for one app.2926. Document app-specific configuration for the next contributor; use293 `agent-native-docs` when the installed package behavior is unclear.2947. Prefer public props and slots; if they cannot express the need, use the295 smallest supported ejection unit. See `customizing-agent-native` for the296 configure → compose → eject → propose seam ladder.2978. Keep one controller as the source of truth for the default and custom render298 paths. A custom design must not fork actions, analytics, async state, or299 accessibility behavior.3009. If the app registers a custom adapter, verify it with the conformance kit,301 including focus, keyboard, dismissal, and portal behavior where components302 meet framework surfaces.303304## Related Skills305306Read these alongside this skill when the work touches the specific area:307308- `sharing`309- `secrets`310- `adding-a-feature`311- `agent-native-docs`312313Use `agent-native-docs` to find installed-version guidance for navigation,314screen context, collaboration, visual direction, and other capabilities not315included in your scaffold's skill set.