Skip to content
Skills Library
AI & agents · Building & coding

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.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

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

agent
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

  1. Classify The Ask First
  2. Where The App Lives
  3. Vault Access
  4. Discovery, Links, And The UI Stack
  5. App Data Goes Through Actions
  6. PostgreSQL Database
  7. Scaffolding
  8. Finishing A Chat-Template App
  9. Related Skills
Original SKILL.md headings · 112 lines, 831 words
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

RepositoryScoreLicence
This page · builderio/agent-native90MIT
builderio/agent-native90MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.