For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/mobile/agents.md (or send Accept: text/markdown).
Build with a coding agent
Hand tasks to a coding agent: the files it reads, the shipped skills, and the review that keeps you in control.
Beginner walkthrough
Prerequisites: Read the two beginner guides below and finish Mobile local setup. A coding agent is an AI tool — Cursor, Claude Code, Devin or a similar assistant — that reads your project, edits files and runs commands. Everything on this page applies to whichever one you use.
Quick terms: a prompt is the instruction text you paste into the agent. A diff is the list of file changes it proposes. The repository root is the top folder containing package.json — the agent should always start there.
1. Open .agents/skills/ in the repository root and copy the skill closest to your task — add-a-mobile-screen is a good first try.
2. Paste it into your agent and describe your change, then add one line: Read llms.txt, then AGENTS.md, then .ai/PROJECT_CONTEXT.md before touching code.
3. Let the agent list the files it will change and the checks it will run before it edits. When it finishes, review the diff — you are approving real changes to your product.
4. Publishing, store submission and paid provider calls are never part of a task prompt. Keep them as separate steps you approve explicitly.
The files your agent reads
The repository ships a small stack of files written for agents, not only for humans. You never paste this context by hand — point the agent at llms.txt and it reads the rest itself.
Read order matters: llms.txt is the map, AGENTS.md sets the boundaries, and .ai/PROJECT_CONTEXT.md carries what earlier sessions learned. An agent that skips the boundaries produces code you cannot ship.
| File | What it gives the agent |
|---|---|
| llms.txt | The repository entry map, generated to list only what this checkout actually ships |
| AGENTS.md | The non-negotiable boundaries: local work only until you approve more, workspaceId scoping, server-only secrets |
| .ai/PROJECT_CONTEXT.md | Cross-session memory — what changed recently and why; read before code changes |
| .ai/ mirror docs | A matching .ai/<path>.md note beside important files, recording per-file decisions and open threads |
| .agents/skills/ | Task runbooks written for agents — the six mobile skills listed below |
| docs/agent-security.md | The acceptance checklist — authentication, workspace and permission checks, redacted logs |
| docs/mobile-store-submission.md | The store release runbook — accounts, builds, review notes and submission order |
| .env.example | The complete environment inventory — the agent never invents a variable name absent from this file |
The shipped skills
Each file under .agents/skills/ is a complete brief: paste it or let the agent read it, and the kit's rules travel with it — server-first data, no secrets in the bundle, offline as a network-error fallback only.
The pasteable prompts/ library ships only in the Web repository; this checkout carries skills instead. For an unattended setup, use the ready prompt in the agent-setup guide.
add-a-mobile-screen— add or change a screen, its data flow and its offline behavioradding-a-dependency— add, upgrade or move an npm dependency safelyreviewing-a-pr— review a diff for correctness, workspace isolation and secretsupgrading-from-upstream— pull a newer kit release into your appverify-changes— choose and run the right checks before handoffwriting-unit-tests— cover new logic with Vitest
How the agent remembers between sessions
Agents have no memory between sessions — the .ai/ folder is the memory. .ai/PROJECT_CONTEXT.md records what changed recently and why. Beside it, a mirror doc such as .ai/apps/mobile/src/ideas/index.md explains the decisions behind apps/mobile/src/ideas/index.ts that the code alone does not show.
The contract is simple: read a file's mirror before editing it, and update the mirror when the change lands. Open Threads entries record unfinished work so the next session resumes instead of starting over. A stale mirror is worse than none — when you review the agent's diff, check that the mirrors of changed files moved with it.
Review the agent's work honestly
A finished task is evidence, not a summary. Before you keep the agent's work, check it the way docs/agent-security.md checks a deployment:
When something is wrong, send the diff back — the agent fixes its own work fastest when you name the failing check. For anything it should never have attempted alone, say so explicitly once; the boundary holds for the rest of the session.
- It ran the tests it claims — ask for the command and its output, not a conclusion.
- Secrets stayed server-only — nothing new carries a
NEXT_PUBLIC_orEXPO_PUBLIC_prefix, and no key was printed into a report or commit. - Every user-owned read and write stayed scoped by
workspaceId— no query trusts an id sent by the browser. - The
.ai/mirror of each changed file moved with the code. - Publishing, deploying and paid provider calls stayed separate steps you approved — the agent never merged, pushed or deployed on its own.
- If a step failed twice, it stopped and reported the failing command instead of improvising around it.
If you want to continue setup, read Native authentication.