adding-workspace-apps
/adding-workspace-apps
How to add an app to an Agent-Native workspace: classifying an "agent" request, scaffolding `apps/<app-name>`, app discovery and descriptions, mounting and base paths, action-first data, and finishing a chat-template app. Use when asked to create, build, scaffold, or generate a new agent or app in a workspace.
- Author
- builderio ↗
- Repository
- agent-native ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
How to add an app to an Agent-Native workspace: classifying an "agent" request, scaffolding `apps/<app-name>`, app discovery and descriptions, mounting and base paths, action-first data, and finishing a chat-template app. Use when asked to create, build, scaffold, or generate a new agent or app in a workspace.
Triggers from the description
Original author description
How to add an app to an Agent-Native workspace: classifying an "agent" request, scaffolding `apps/<app-name>`, app discovery and descriptions, mounting and base paths, action-first data, and finishing a chat-template app. Use when asked to create, build, scaffold, or generate a new agent or app in a workspace.
How it works
- Classify The Ask First
- Where The App Lives
- Vault Access
- Discovery, Links, And The UI Stack
- App Data Goes Through Actions
- PostgreSQL Database
- Scaffolding
- Finishing A Chat-Template App
- Related Skills
SKILL.md preview
---
name: adding-workspace-apps
description: >-
How to add an app to an Agent-Native workspace: classifying an "agent"
request, scaffolding `apps/<app-name>`, app discovery and descriptions,
mounting and base paths, action-first data, and finishing a chat-template app.
Use when asked to create, build, scaffold, or generate a new agent or app in a
workspace.
scope: dev
---
# Adding Workspace Apps
## Classify The Ask First
When a user asks from Dispatch chat or through `@agent-native` in Slack or
Telegram to create, build, make, scaffold, or generate an "agent", classify
the ask first.
Simple Dispatch-native behavior such as a reminder, digest, monitor, routing
rule, saved instruction, or recurring workflow can stay in Dispatch as a
recurring job/resource/destination. Robust unique products or teammates that
need their own UI, data model, actions, integrations, or domain workflow should
become a separate workspace app under `apps/<app-name>`, mounted at
`/<app-name>`.
## Where The App Lives
Do not implement a new app by adding a route, page, component, or file to
`apps/chat` or another existing app unless the user explicitly asks to modify
that existing app.
## Vault Access
Dispatch vault access is workspace-wide by default: every saved vault key is
available to every workspace app. Only create or request per-app vault grants
when Dispatch's vault access setting is switched to manual mode.
When an app needs a provider credential, use the app's scoped secret or
workspace-connection resolver so Dispatch remains the source of truth. Do not
ask a non-admin builder to add a key to local project settings or `.env`; use
Dispatch's vault request workflow for a missing key and keep the value out of
app code.
## Discovery, Links, And The UI Stack
The local workspace gateway discovers apps from
`apps/<app-name>/package.json`. Production Dispatch images that contain only
`.output/` cannot scan those directories: set `AGENT_NATIVE_WORKSPACE_APPS_JSON`
on the Dispatch service at runtime and the same
`VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON` while building its client bundle. List
only apps in that workspace, with each deployed `path` matching its
`APP_BASE_PATH` and proxy route. Do not reuse another organization's manifest.
Always save a concise, human-readable `description` in each package manifest;
Dispatch and A2A connected-agent context use the app name plus description so
agents know what it does. Use relative workspace links like `/<app-name>` and never
hardcode `localhost`, `127.0.0.1`, `8080`, `8100`, or any dev port in app
cards, instructions, redirects, or navigation; the active workspace
gateway/browser origin owns the port. React Router apps must keep the
`configureClientRouterBasename()` call in `app/entry.client.tsx`, before
`hydrateRoot`, so the app hydrates correctly when mounted at `/<app-name>`.
Use the framework/template UI stack for standard UI:
shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or
another icon library. Read `.agents/skills/shadcn-ui/SKILL.md` before adding,
updating, or debugging shadcn components.
## App Data Goes Through Actions
Normal app data must flow through actions. For CRUD that the agent can perform,
create `defineAction` files in `actions/`, mark reads with
`http: { method: "GET" }`, and call them from React with `useActionQuery` /
`useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for
the same data unless the route is for uploads, streaming, webhooks, OAuth, or
another route-only concern. Do not add routes whose main job is to wrap,
proxy, or re-export an action; the action endpoint already exists at
`/_agent-native/actions/:name`. Action-backed UI is what makes agent-created or
agent-edited records appear without a manual refresh.
## PostgreSQL Database
App database code targets local PGlite and hosted Postgres. Define schemas with
`@agent-native/core/db/schema` helpers and write app reads/writes with Drizzle's
PostgreSQL query builder and `drizzle-orm` operators. Do not import raw schema
drivers in app templates. Keep raw SQL
for additive migrations, health checks, or carefully scoped maintenance. Do not use SQL as object
storage; file bytes belong in upload/private-blob providers with only references
saved to app tables.
## Scaffolding
In local development, run
`pnpm exec agent-native add-app <app-name> --template=<template>` from the
workspace root. In production, Dispatch posts new-app requests to Builder
branch creation; Builder should still scaffold the separate workspace app. The
workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories
automatically.
Scaffolding the directory is not the app being live. Before saying the app is
created, request `/<app-name>` on the running gateway and confirm it returns
the new app, not a fallback route or another app's shell — then tell the user
that exact path to open, since the preview root can still show a different
app. If the preview/host isn't running the workspace gateway (root `pnpm
dev`), say plainly that its run/dev command must point at the workspace root
`pnpm dev` and name where to set it (Builder: project settings → dev
command); the agent cannot change a host's run/dev command itself. Never
report the app as created while the preview still shows something else.
## Finishing A Chat-Template App
When using the chat template, treat it as scaffolding only. The finished app
must be branded as the requested app, with its own home screen, navigation,
package metadata, manifest, and domain workflow. Do not leave visible
`Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived
app.
## Related Skills
- **workspace-conventions** — Shared workspace rules this workflow assumes.
- **actions** — How to define the app operations the agent and UI share.
- **composable-mini-apps** — Splitting work across focused sibling apps.
- **portability** — Keeping PostgreSQL and hosting assumptions explicit.
- **shadcn-ui** — Adding and upgrading the UI primitives.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · builderio/agent-native | 90 | MIT |
| builderio/agent-native | 90 | MIT |
Database snapshot: 13.11.2026 · package version 2a7d8377425c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100writing-agent-instructions
How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool/action descriptions. Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs in instructions vs skills vs memory. - 100create-mcp-app
This skill should be used when the user asks to "create an MCP App", "add a UI to an MCP tool", "build an interactive MCP View", "scaffold an MCP App", or needs guidance on MCP Apps SDK patterns, UI-resource registration, MCP App lifecycle, or host integration. Provides… - 100canvas-extension-api
This skill should be used when the user asks to "create an OpenHands App", "scaffold a Canvas App", "build an app with the Canvas Extensions API", "build an Agent Canvas App", "bundle a single-file Canvas App", "build a Sidecar-backed Canvas App", "add onboarding for an App… - 100customizing-agent-native
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. - 86mobile-app-dev
Use when scaffolding or deploying Expo/React Native apps. - 100create-mcp-app
This skill should be used when the user asks to "create an MCP App", "add a UI to an MCP tool", "build an interactive MCP View", or needs guidance on MCP Apps SDK patterns, UI-resource registration, MCP App lifecycle, or host integration. Provides guidance for building MCP Apps with interactive UIs.