Build an App
Done means one useful domain workflow with a designed route, shared UI/agent
actions, correct access, agent context, and a smoke run that proves its key
rule. Finish a narrow slice before expanding it.
This skill edits source files. If this session cannot write files (a deployed
app's runtime agent), say the change needs a code session and stop.
The four-area parity rule from adding-a-feature (UI, action, instructions,
application state) applies to everything you add. This skill supplies the
order and decisions; use the edit-point reference for the scaffold you have.
1. Orient
Read AGENTS.md, this skill, and only the files you will edit. Skip broad repo
surveys, README.md, and DESIGN.md. Use the bundled docs/source commands in
AGENTS.md only to answer a concrete API question; do not web-research
framework APIs.
2. Decide
Choose these six things before writing code:
- Slice: the one workflow that proves the app. For a booking app: create a
booking, reject an overlap, cancel, weekly grid per room. Name what you are
deferring (recurrence, notifications, roles, integrations) unless requested.
- Who sees each table: pick one row of the access table in
references/data-and-access.md: private, team-visible, shared on invite, or a
child that inherits its parent's access. Making a team resource private per
user is the usual wrong turn. Everyone then sees an empty list, and no
conflict check can see anyone else's rows. Give each table owner_email
and/or org_id, directly or via ownableColumns(); org_id alone passes
[db-tool-scoping]. Doctor checks the schema marker, not query authorization;
never denylist or opt out rooms or bookings.
- Invariants: rules that must hold under concurrent requests (no overlap,
stock never negative, unique slug). Enforce them in a write action inside a
transaction or with a database constraint; the UI alone is insufficient.
- Actions:
list-<things>, create-<thing>, a single update-<thing>
patch per resource, and the domain verbs (cancel-booking). Fewer,
orthogonal tools make the agent choose better.
- Route: give the domain its own route (for example,
/rooms). Preserve
existing routes and set app.homePath so sign-in lands on the domain when
that is the requested home screen.
- Agent context: URL ids and filters (for example
roomId, week) that
belong in navigation.
3. Build: write everything, then verify once
In a generated app, read package.json at
["agent-native"].scaffold.template and choose the matching reference:
chat: references/edit-points-chat.md
default: references/edit-points-default.md
- workspace root: use
adding-workspace-apps to create an app, then follow the
new app's own AGENTS.md and scaffold reference.
- another domain template: use its
AGENTS.md and adding-a-feature; do not
apply Chat or default shell instructions to it.
If metadata is absent, inspect the actual route, layout, plugin, and navigation
files before choosing an edit point. Do not infer a shell from the app name.
Write the UI, actions, instructions, and state before running the verification
steps below. Do not leave placeholder or comment-only screens.
references/rooms-example.md gives a booking slice to adapt. It was verified
against the Chat starter; use the selected edit-point reference for the shell.
Use frontend-design for a deliberate visual direction and finish the
requested screens and interactions.
Data
- Use PostgreSQL only, and keep migrations additive: new columns are nullable
or have a default, and nothing is dropped or renamed. Never edit an applied
entry; append a new named one.
- Set
ownerEmail from ctx.userEmail and orgId from ctx.orgId on inserts
where those columns exist. Never rely on a development identity fallback.
- Ids are text from
crypto.randomUUID().
- Bound every list (a time range or
.limit()), select only the columns it
renders, and index the columns it filters and sorts on.
- Store normalized UTC ISO timestamps; collect/display local times in the
user's timezone. Validate offsets at the action boundary before parsing.
The access table, the concurrency pattern, and the security rules are in
references/data-and-access.md.
Actions
schema is zod, with .describe() on every field stating its units and
format (for example, "ISO 8601 date-time with offset").
- Reads use
http: { method: "GET" } and readOnly: true. Leave writes on the
default POST so useActionMutation needs no method.
- Reject with
fail(message, { errorCode, statusCode }) from
@agent-native/core/action: 409 for a conflict, 404 for not found, 403 for
forbidden. A returned { error } is counted as success everywhere, and a
bare throw reaches the browser as a generic 500.
- Return plain objects that include the
id. Keep LLM calls out of actions;
AI-shaped work belongs in the agent chat.
- When the request is batch-shaped ("add these 20"), write one action that
takes an array and writes it in one transaction.
UI
- Load and write data with
useActionQuery and useActionMutation from
@agent-native/core/client/hooks. No fetch, and no /api/* routes for app
data. Those routes are only for uploads, webhooks, OAuth callbacks, and streaming.
- While data loads, show a
Skeleton in the shape of the final layout, not a
spinner or "Loading…".
- Writes should feel instant. In
onMutate, update ["action", "<name>", params]
with setQueryData; in onError, roll back and show
toast.error(actionErrorMessage(error) ?? "<fallback>").
- Import controls from
@/components/ui/*. When one is missing (dialog,
select, skeleton, alert-dialog), add a one-line re-export like button.tsx:
export * from "@agent-native/toolkit/ui/dialog";.
- Use Tabler icons only. Confirm with
AlertDialog; never use window.confirm,
alert, or prompt.
- Don't add a page title that repeats the nav item, a subtitle under a title,
or a stats strip. The data is the page. For visual direction, see
frontend-design.
- Follow the app's existing localization pattern for user-facing copy.
- Add a pure
link builder with buildDeepLink() to actions that create or
list navigable resources; see adding-a-feature for the shape.
Agent instructions
Append one section of about 1,500 characters at most to AGENTS.md. The
runtime prompt cuts the file off at 6,000 characters. Cover:
- a one-line purpose with the routes
- the invariants, and how to report a rejection
- time and format conventions
- the new
navigation fields
- an action table with unpadded cells
Keep the action table aligned with the scaffold's primary tool list when one
exists; other actions should remain discoverable through tool-search. Leave
unrelated AGENTS.md sections, README, and DESIGN.md as they are.
Real-time
Agent writes need no wiring, because the chat run refreshes action queries
after each tool. Add useDbSync({ realtime: { reason } }) to a page only when
other people change its data while it is open and the user must see the change
before refreshing. A booking grid doesn't qualify: the server rejects bookings
made from a stale view. See real-time-sync.
4. Verify, once, in this order
Start pnpm exec agent-native dev in the background, without --open, and
wait for the ready URL. Startup regenerates .generated/action-types.d.ts
and the actions registry, so a typecheck run before this is meaningless.
On loopback, automatic dev sign-in works when the local database has no real
users. If the sign-in page appears, use an existing local account or switch
to a separate disposable local database; do not create accounts or set
AUTH_DISABLED.
Run pnpm typecheck, then pnpm agent-native:doctor. Plain pnpm doctor
runs pnpm's own command and exits 0 without running Agent-Native Doctor. Fix
every finding, then rerun only what failed.
Check the agent path. Call a guarded write twice with the same input via
pnpm action <name> --key value. The second call must fail with the expected
message; read back the saved state through the matching list/get action.
The CLI prints the failure message, not its structured errorCode, so also
verify any code-specific behavior in the action contract or browser.
Run one browser smoke on the domain route:
- create a record
- trigger the rejection: a toast appears and nothing is written
- cancel or undo, repeat the previously rejected write, and confirm it
succeeds
Inspect console and network failures. Fix errors from the new route or actions
and identify existing scaffold messages separately. The only expected 4xx/5xx
is the rejection being tested. Capture the finished workflow.
Stop the dev server and close the tab.
Skip the production build, unrelated test suites, and README or DESIGN rewrites.
To triage failures, see references/verification.md.
5. Report
State what works and the proof, what you deferred, and anything the user still
has to do (for example, set DATABASE_URL before deploying). Never report a
check you didn't run.
Related
adding-a-feature: the parity checklist for each later feature in this app.
frontend-design, actions, sharing, real-time-sync, and security:
go deeper on one area when the references aren't enough.
1---2name: build-an-app3description: >-4 Fast end-to-end workflow for turning this starter into a working domain app5 from a short or vague request. Use when asked to build, make, create, or6 prototype an app, tool, tracker, dashboard, booking, inventory, or CRM7 system with Agent-Native. Read before the first edit.8scope: both9metadata:10 source: https://skillmd.com/skills/builderio/build-an-app11 internal: true12---1314# Build an App1516Done means one useful domain workflow with a designed route, shared UI/agent17actions, correct access, agent context, and a smoke run that proves its key18rule. Finish a narrow slice before expanding it.1920This skill edits source files. If this session cannot write files (a deployed21app's runtime agent), say the change needs a code session and stop.2223The four-area parity rule from `adding-a-feature` (UI, action, instructions,24application state) applies to everything you add. This skill supplies the25order and decisions; use the edit-point reference for the scaffold you have.2627## 1. Orient2829Read `AGENTS.md`, this skill, and only the files you will edit. Skip broad repo30surveys, `README.md`, and `DESIGN.md`. Use the bundled docs/source commands in31`AGENTS.md` only to answer a concrete API question; do not web-research32framework APIs.3334## 2. Decide3536Choose these six things before writing code:37381. **Slice**: the one workflow that proves the app. For a booking app: create a39 booking, reject an overlap, cancel, weekly grid per room. Name what you are40 deferring (recurrence, notifications, roles, integrations) unless requested.412. **Who sees each table**: pick one row of the access table in42 `references/data-and-access.md`: private, team-visible, shared on invite, or a43 child that inherits its parent's access. Making a team resource private per44 user is the usual wrong turn. Everyone then sees an empty list, and no45 conflict check can see anyone else's rows. Give each table `owner_email`46 and/or `org_id`, directly or via `ownableColumns()`; `org_id` alone passes47 `[db-tool-scoping]`. Doctor checks the schema marker, not query authorization;48 never denylist or opt out `rooms` or `bookings`.493. **Invariants**: rules that must hold under concurrent requests (no overlap,50 stock never negative, unique slug). Enforce them in a write action inside a51 transaction or with a database constraint; the UI alone is insufficient.524. **Actions**: `list-<things>`, `create-<thing>`, a single `update-<thing>`53 patch per resource, and the domain verbs (`cancel-booking`). Fewer,54 orthogonal tools make the agent choose better.555. **Route**: give the domain its own route (for example, `/rooms`). Preserve56 existing routes and set `app.homePath` so sign-in lands on the domain when57 that is the requested home screen.586. **Agent context**: URL ids and filters (for example `roomId`, `week`) that59 belong in `navigation`.6061## 3. Build: write everything, then verify once6263In a generated app, read `package.json` at64`["agent-native"].scaffold.template` and choose the matching reference:6566- `chat`: `references/edit-points-chat.md`67- `default`: `references/edit-points-default.md`68- workspace root: use `adding-workspace-apps` to create an app, then follow the69 new app's own `AGENTS.md` and scaffold reference.70- another domain template: use its `AGENTS.md` and `adding-a-feature`; do not71 apply Chat or default shell instructions to it.7273If metadata is absent, inspect the actual route, layout, plugin, and navigation74files before choosing an edit point. Do not infer a shell from the app name.7576Write the UI, actions, instructions, and state before running the verification77steps below. Do not leave placeholder or comment-only screens.7879`references/rooms-example.md` gives a booking slice to adapt. It was verified80against the Chat starter; use the selected edit-point reference for the shell.81Use `frontend-design` for a deliberate visual direction and finish the82requested screens and interactions.8384### Data8586- Use PostgreSQL only, and keep migrations additive: new columns are nullable87 or have a default, and nothing is dropped or renamed. Never edit an applied88 entry; append a new named one.89- Set `ownerEmail` from `ctx.userEmail` and `orgId` from `ctx.orgId` on inserts90 where those columns exist. Never rely on a development identity fallback.91- Ids are text from `crypto.randomUUID()`.92- Bound every list (a time range or `.limit()`), select only the columns it93 renders, and index the columns it filters and sorts on.94- Store normalized UTC ISO timestamps; collect/display local times in the95 user's timezone. Validate offsets at the action boundary before parsing.9697The access table, the concurrency pattern, and the security rules are in98`references/data-and-access.md`.99100### Actions101102- `schema` is zod, with `.describe()` on every field stating its units and103 format (for example, "ISO 8601 date-time with offset").104- Reads use `http: { method: "GET" }` and `readOnly: true`. Leave writes on the105 default POST so `useActionMutation` needs no `method`.106- Reject with `fail(message, { errorCode, statusCode })` from107 `@agent-native/core/action`: 409 for a conflict, 404 for not found, 403 for108 forbidden. A returned `{ error }` is counted as success everywhere, and a109 bare `throw` reaches the browser as a generic 500.110- Return plain objects that include the `id`. Keep LLM calls out of actions;111 AI-shaped work belongs in the agent chat.112- When the request is batch-shaped ("add these 20"), write one action that113 takes an array and writes it in one transaction.114115### UI116117- Load and write data with `useActionQuery` and `useActionMutation` from118 `@agent-native/core/client/hooks`. No `fetch`, and no `/api/*` routes for app119 data. Those routes are only for uploads, webhooks, OAuth callbacks, and streaming.120- While data loads, show a `Skeleton` in the shape of the final layout, not a121 spinner or "Loading…".122- Writes should feel instant. In `onMutate`, update `["action", "<name>", params]`123 with `setQueryData`; in `onError`, roll back and show124 `toast.error(actionErrorMessage(error) ?? "<fallback>")`.125- Import controls from `@/components/ui/*`. When one is missing (dialog,126 select, skeleton, alert-dialog), add a one-line re-export like `button.tsx`:127 `export * from "@agent-native/toolkit/ui/dialog";`.128- Use Tabler icons only. Confirm with `AlertDialog`; never use `window.confirm`,129 `alert`, or `prompt`.130- Don't add a page title that repeats the nav item, a subtitle under a title,131 or a stats strip. The data is the page. For visual direction, see `frontend-design`.132- Follow the app's existing localization pattern for user-facing copy.133- Add a pure `link` builder with `buildDeepLink()` to actions that create or134 list navigable resources; see `adding-a-feature` for the shape.135136### Agent instructions137138Append one section of about 1,500 characters at most to `AGENTS.md`. The139runtime prompt cuts the file off at 6,000 characters. Cover:140141- a one-line purpose with the routes142- the invariants, and how to report a rejection143- time and format conventions144- the new `navigation` fields145- an action table with unpadded cells146147Keep the action table aligned with the scaffold's primary tool list when one148exists; other actions should remain discoverable through `tool-search`. Leave149unrelated AGENTS.md sections, README, and DESIGN.md as they are.150151### Real-time152153Agent writes need no wiring, because the chat run refreshes action queries154after each tool. Add `useDbSync({ realtime: { reason } })` to a page only when155other people change its data while it is open and the user must see the change156before refreshing. A booking grid doesn't qualify: the server rejects bookings157made from a stale view. See `real-time-sync`.158159## 4. Verify, once, in this order1601611. Start `pnpm exec agent-native dev` in the background, without `--open`, and162 wait for the ready URL. Startup regenerates `.generated/action-types.d.ts`163 and the actions registry, so a typecheck run before this is meaningless.164 On loopback, automatic dev sign-in works when the local database has no real165 users. If the sign-in page appears, use an existing local account or switch166 to a separate disposable local database; do not create accounts or set167 `AUTH_DISABLED`.1682. Run `pnpm typecheck`, then `pnpm agent-native:doctor`. Plain `pnpm doctor`169 runs pnpm's own command and exits 0 without running Agent-Native Doctor. Fix170 every finding, then rerun only what failed.1713. Check the agent path. Call a guarded write twice with the same input via172 `pnpm action <name> --key value`. The second call must fail with the expected173 message; read back the saved state through the matching list/get action.174 The CLI prints the failure message, not its structured `errorCode`, so also175 verify any code-specific behavior in the action contract or browser.1764. Run one browser smoke on the domain route:177 - create a record178 - trigger the rejection: a toast appears and nothing is written179 - cancel or undo, repeat the previously rejected write, and confirm it180 succeeds181182 Inspect console and network failures. Fix errors from the new route or actions183 and identify existing scaffold messages separately. The only expected 4xx/5xx184 is the rejection being tested. Capture the finished workflow.1855. Stop the dev server and close the tab.186187Skip the production build, unrelated test suites, and README or DESIGN rewrites.188To triage failures, see `references/verification.md`.189190## 5. Report191192State what works and the proof, what you deferred, and anything the user still193has to do (for example, set `DATABASE_URL` before deploying). Never report a194check you didn't run.195196## Related197198- `adding-a-feature`: the parity checklist for each later feature in this app.199- `frontend-design`, `actions`, `sharing`, `real-time-sync`, and `security`:200 go deeper on one area when the references aren't enough.