---
name: oneapp-builder
description: Create or update personal App Jam experiences through its connected MCP service. Use for agent-authored apps, dashboards, learning tools, and package updates; not for modifying the App Jam host or operating its infrastructure.
---

# App Jam Builder

Turn the user's request into an experience delivered to their signed-in App Jam account. This skill works without prior chat history or a checkout of the host repository.

App Jam was formerly called One App. The existing `oneapp` connector, `oneapp-builder` skill name, service URLs, `oneapp://` resources and protocol identifiers remain compatible; use them unchanged.

## Connect and discover

Use an existing authorized `oneapp` MCP connection. If unavailable, read [connections](references/connections.md) and the operator-supplied [service metadata](references/service.json). The client performs OAuth discovery and opens App Jam account sign-in/consent. Never ask the user for a relay URL, owner/admin token, MCP bearer token, or provider API key to author or publish. Do not invent a production endpoint. Do not collect account passwords in chat; the person completes browser sign-in themselves.

Inspect the actual MCP tool catalog, host capabilities, package schema, authoring resource, authorized devices, and current app/table catalog. Discover the available example catalog and read relevant full example packages to learn supported composition and asset conventions. Tool names in this kit are hints, not substitutes for discovery. Examples explain the platform; they are not evidence that the user's app has been created. Use the person's selected device; ask if several plausible devices remain. A catalog contains metadata, not a live personal-record mirror. Use record-read authority only when the request actually needs existing personal content.

When improving an existing app, retrieve its actual source before replacing it. Read [source handoff](references/source-handoff.md) for the authorized, revision-pinned package reader available in host0.3.0. It excludes personal records and credentials; new source access needs its own OAuth permission. If neither source nor that capability is available, explain what is missing instead of publishing a replacement that loses the existing app's behavior or storage identity.

If a named tool or resource is absent, follow the [discovery fallbacks](references/connections.md#discovery-fallbacks). Clients may cache a tool list or omit resource access. Read the HTTP authoring/schema artifacts when necessary; never call an undiscovered tool or ask for account secrets to repair discovery.

## Understand the person before building

Speak in terms of what the app will do. Ask only a few task-relevant questions whose answers are missing: what data/source they want to use, how they want to use the app, and what must work without internet. Reuse answers already given. Offer sensible defaults, explain a real tradeoff when it changes the experience, and recommend an option rather than making the person choose an API, backend, or framework. After discovery and any needed answers, briefly state the intended experience and its limits before authoring it.

## Build the requested experience

Read [authoring](references/authoring.md) for package rules and runtime choices. For Chinese vocabulary, section quizzes, and mistake review, also read [the learning acceptance reference](references/chinese-learning.md).
For alerts, scheduled tasks or reminders, read [notification readiness](references/notifications.md) before promising background or recurring behavior.
Use [design guidance](references/design.md) for clear names/copy, a bounded mobile app shell with anchored actions and scrolling content panes, accessible layouts, offline/API declarations, and meaningful touch/lifecycle checks. A quiz or board game should keep its question or board in view; do not default to a long scrolling webpage. For Home themes, fullscreen controls or bundled experience icons, read [host customization](references/host-customization.md); discover the selected device's version before promising these features.

- Prefer existing tables and stable IDs. Retain user records, prior attempts, photos, and credential references across updates. Seeds insert missing rows; they do not update or reset personal data.
- Choose native only when the discovered compiled components and actions support the requested interaction. A schema's generic JSON `props` field does not make an unknown prop functional. When native capability is missing, explain the user-visible limitation and recommend a locally packaged HTML experience or an appropriate platform upgrade. Ask about a material compromise before building it; never fake a feature by editing the host's screens.
- Native packages contain data/assets and bounded built-in actions, never customer React Native bundles or executable native plugins. HTML packages include their scripts, styles, and assets locally. Baseline HTML has no privileged host bridge; a separately consented development bridge is not an approved shipping capability.
- Build a package for the connected platform. Do not generate a separate Next.js, Swift, Expo, or other host project as a substitute for publishing a personal experience. Do not require the person to supply the whole repository or earlier conversation.
- Declare actual offline behavior and provider requirements using the discovered schema. In host0.5.0 use `offline` and `credentialRequirements` with the corresponding minimum host version; legacy omission is unknown. Games and vocabulary practice need no paid AI by default. Keep local workflows functional offline and retain the last good installed package on update failure. Online APIs remain online. Reference configured credential IDs only when needed; a learning app does not require paid AI. Optional provider setup happens within App Jam, never by pasting keys into chat, source, headers, or shell commands.
- Import only user-provided or explicitly permitted content. Preserve source/section provenance; do not imply a source was fetched when it was not.

## Publish and verify

Validate against the discovered schema and runtime behavior. Set stable `experienceId`, the intended runtime, `baseRevision` to that installed variant's revision (0 for first install), and a higher `revision`. Include concise release notes. Publish with a stable operation ID so transport retries do not create duplicate work.

Save the experience definition as `experience.json`. Keep any npm build manifest in a separate `package.json`; installing build dependencies must not alter the experience definition.

When the connected service advertises `validate_experience`, run it before publishing and inspect its safe errors and known-device revision warnings. Read and parse local package files into JSON objects; `$file:/path` strings are client-specific and cannot make the hosted service read your filesystem. A successful preflight still does not install anything. Do not bump the package revision to work around an input-format error.
Inspect `nativeWarnings` as well: they identify ignored properties, children or actions by tree path and list supported property names. Remove unused configuration; if a requested feature depends on it, choose a supported implementation or explain the real limitation. Never describe an accepted but ignored prop as a working feature. The package schemas describe authoring inputs; omitted defaults are filled by parsing, not mandatory fields the agent must invent.

Once the requested app is authorized and passes the discovered validation, publish it immediately. Do not wait for the person to say they opened or upgraded App Jam. Use the package's real `minHostVersion`; when the service supports version-aware delivery, a package for a newer host can be accepted as `status:"queued"` with `installation:"awaiting_host"`. Tell the person to install the required host update and open App Jam online before the queue expires. A compatible queued update installs automatically during opening/sync; no further chat confirmation is needed. Do not lower the minimum version or invent unsupported components to bypass validation.

Inspect the returned operation acknowledgement. `queued` means waiting, not installed. `awaiting_host` needs a compatible host; `awaiting_device` needs device processing. Make a reasonable status check with backoff, and check again if the person later asks or device activity changes. If the phone is unavailable, leave the operation queued and report its ID/status instead of busy polling. With `push:not-configured`, tell the person once to open App Jam online; this is an instruction, not a confirmation gate. Notifications can alert the person but do not guarantee background installation. Report `applied` only from an actual device acknowledgement and confirm the installed revision from the synchronized catalog. On failure, fix the concrete schema/capability/conflict error without resetting user data. On authentication/account-access failure, use normal sign-in rather than requesting an administrator token.

Finish with the experience name, actual delivery status, tested/offline behavior and any remaining capability limits. Keep runtime/revision details in diagnostics unless needed to explain a decision; ordinary app titles and copy should describe its purpose. No App Store approval, live API result, device installation, or compatibility claim follows merely from generating a package.

For backup/storage or recovery questions, read [backups](references/backups.md). Never request recovery keys or provider secrets in chat. Host0.5 has encrypted saved-copy recovery; live multi-device data sync is a separate capability.