PowerSync Skills
Use this skill to onboard a project onto PowerSync without trial-and-error. Treat this as a guided workflow first and a reference library second.
Agents: Read AGENTS.md before proceeding. It contains the mandatory compliance rules and onboarding playbook. The Quick Rules below are a reminder, not a substitute. powersync login is PowerSync Cloud only (PAT); self-hosted does not use it.
Terminology
- Operator — the human directing this agent (whose request you are fulfilling).
- User — an end-user of the operator's PowerSync app (JWT subjects, the row a sync stream filters by, the person calling
disconnectAndClear()).
If a sentence is ambiguous, default to the operator interpretation. Full legend in AGENTS.md.
Quick Rules
- CLI-first. Use the PowerSync CLI for all operations. Do not hand-write config files. See
references/powersync-cli.md.
- Ask, don't assume. Ask the operator: Cloud vs self-hosted, and which backend (Supabase, Postgres, MongoDB, MySQL, MSSQL). Do not default to Supabase.
- Backend before frontend. Deploy sync config and verify the service before writing app code.
- Sync Streams for new projects. Sync Rules are legacy.
- Persist credentials immediately. Write all URLs and keys to
.env as soon as they are available.
- Default scope on existing projects: sync-config only. Do not edit
service.yaml or cli.yaml unless the operator explicitly authorized service/infra changes in this conversation.
- Confirm the target instance before any mutating command (
deploy, destroy, stop, link --create, pull instance). Never deploy to an instance not authorized by the operator. Treat production as off-limits unless explicitly approved.
- Use project memory. If your harness supports it, persist the CLI invocation, sync-config path, authorized instance ids + environment (dev/staging/prod), and allowed scope of changes. Verify saved values still match reality before acting on them. See
AGENTS.md § "Continuous Use & Guardrails".
What to Load for Your Task
| Task |
Start with |
Load on demand |
| Supabase + PowerSync |
references/onboarding-supabase.md |
references/supabase-auth.md, references/sync-config.md, SDK files |
| Custom backend (non-Supabase) |
references/onboarding-custom.md |
references/custom-backend.md, references/sync-config.md, SDK files |
| New project setup |
references/powersync-cli.md + references/powersync-service.md |
references/sync-config.md, SDK files |
| Self-hosting / service config |
references/powersync-service.md + references/powersync-cli.md |
references/sync-config.md |
| Writing sync config |
references/sync-config.md |
— |
| Debugging sync issues |
references/powersync-debug.md |
— |
| Raw Tables (advanced) |
references/raw-tables.md |
— |
| Attachments |
references/attachments.md |
— |
| Architecture overview |
references/powersync-overview.md |
— |
SDK Reference Files
JavaScript / TypeScript
Always load references/sdks/powersync-js.md for any JS/TS project, then load the applicable framework file.
| Framework |
File |
Load early if… |
| React / Next.js |
references/sdks/powersync-js-react.md |
Vite + React project — contains the required vite.config.ts setup (optimizeDeps.exclude, worker.format: 'es') needed before installing packages |
| React Native / Expo |
references/sdks/powersync-js-react-native.md |
|
| Vue / Nuxt |
references/sdks/powersync-js-vue.md |
|
| Node.js / Electron |
references/sdks/powersync-js-node.md |
|
| TanStack |
references/sdks/powersync-js-tanstack.md |
|
| Drizzle / Kysely ORM |
references/sdks/powersync-js-orm.md |
Project uses Drizzle or Kysely |
Other SDKs
| Platform |
File |
| Dart / Flutter |
references/sdks/powersync-dart.md |
| .NET |
references/sdks/powersync-dotnet.md |
| Kotlin |
references/sdks/powersync-kotlin.md |
| Swift |
references/sdks/powersync-swift.md |
Key Rules to Apply Without Being Asked
- Never define the
id column in a PowerSync table schema; it is created automatically.
- Use
column.integer for booleans and column.text for ISO date strings.
connect() is fire-and-forget. Use waitForFirstSync() if you need readiness.transaction.complete() is mandatory or the upload queue stalls permanently.disconnectAndClear() is required on logout or user switch when local data must be wiped.- A 4xx response from
uploadData blocks the upload queue permanently; return 2xx for validation errors.
1---2name: powersync3description: Guided onboarding and best practices for building applications with PowerSync — Cloud and self-hosted setup, sync configuration, client SDK usage, backend integration (Supabase, custom Postgres, MongoDB, MySQL, MSSQL), and debugging. Use this skill whenever the user mentions PowerSync, offline-first sync, local-first architecture, sync rules, sync streams, uploadData, fetchCredentials, real-time data replication, or wants to add offline-capable sync to a mobile or web app — even if they don't explicitly name PowerSync.4license: MIT5---6
7# PowerSync Skills
8
9Use this skill to onboard a project onto PowerSync without trial-and-error. Treat this as a guided workflow first and a reference library second.
10
11**Agents: Read [AGENTS.md](AGENTS.md) before proceeding.** It contains the mandatory compliance rules and onboarding playbook. The Quick Rules below are a reminder, not a substitute. **`powersync login`** is **PowerSync Cloud only** (PAT); self-hosted does not use it.
12
13## Terminology
14
15- **Operator** — the human directing this agent (whose request you are fulfilling).
16- **User** — an end-user of the operator's PowerSync app (JWT subjects, the row a sync stream filters by, the person calling `disconnectAndClear()`).
17
18If a sentence is ambiguous, default to the operator interpretation. Full legend in `AGENTS.md`.
19
20## Quick Rules
21
22- **CLI-first.** Use the [PowerSync CLI](https://docs.powersync.com/tools/cli.md) for all operations. Do not hand-write config files. See `references/powersync-cli.md`.
23- **Ask, don't assume.** Ask the operator: Cloud vs self-hosted, and which backend (Supabase, Postgres, MongoDB, MySQL, MSSQL). Do not default to Supabase.
24- **Backend before frontend.** Deploy sync config and verify the service before writing app code.
25- **Sync Streams for new projects.** Sync Rules are legacy.
26- **Persist credentials immediately.** Write all URLs and keys to `.env` as soon as they are available.
27- **Default scope on existing projects: sync-config only.** Do not edit `service.yaml` or `cli.yaml` unless the operator explicitly authorized service/infra changes in this conversation.
28- **Confirm the target instance before any mutating command** (`deploy`, `destroy`, `stop`, `link --create`, `pull instance`). Never deploy to an instance not authorized by the operator. Treat production as off-limits unless explicitly approved.
29- **Use project memory.** If your harness supports it, persist the CLI invocation, sync-config path, authorized instance ids + environment (dev/staging/prod), and allowed scope of changes. Verify saved values still match reality before acting on them. See `AGENTS.md` § "Continuous Use & Guardrails".
30
31## What to Load for Your Task
32
33| Task | Start with | Load on demand |
34|------|-----------|----------------|
35| Supabase + PowerSync | `references/onboarding-supabase.md` | `references/supabase-auth.md`, `references/sync-config.md`, SDK files |
36| Custom backend (non-Supabase) | `references/onboarding-custom.md` | `references/custom-backend.md`, `references/sync-config.md`, SDK files |
37| New project setup | `references/powersync-cli.md` + `references/powersync-service.md` | `references/sync-config.md`, SDK files |
38| Self-hosting / service config | `references/powersync-service.md` + `references/powersync-cli.md` | `references/sync-config.md` |
39| Writing sync config | `references/sync-config.md` | — |
40| Debugging sync issues | `references/powersync-debug.md` | — |
41| Raw Tables (advanced) | `references/raw-tables.md` | — |
42| Attachments | `references/attachments.md` | — |
43| Architecture overview | `references/powersync-overview.md` | — |
44
45## SDK Reference Files
46
47### JavaScript / TypeScript
48
49Always load `references/sdks/powersync-js.md` for any JS/TS project, then load the applicable framework file.
50
51| Framework | File | Load early if… |
52|-----------|------|----------------|
53| React / Next.js | `references/sdks/powersync-js-react.md` | Vite + React project — contains the required `vite.config.ts` setup (`optimizeDeps.exclude`, `worker.format: 'es'`) needed before installing packages |
54| React Native / Expo | `references/sdks/powersync-js-react-native.md` | |
55| Vue / Nuxt | `references/sdks/powersync-js-vue.md` | |
56| Node.js / Electron | `references/sdks/powersync-js-node.md` | |
57| TanStack | `references/sdks/powersync-js-tanstack.md` | |
58| Drizzle / Kysely ORM | `references/sdks/powersync-js-orm.md` | Project uses Drizzle or Kysely |
59
60### Other SDKs
61
62| Platform | File |
63|----------|------|
64| Dart / Flutter | `references/sdks/powersync-dart.md` |
65| .NET | `references/sdks/powersync-dotnet.md` |
66| Kotlin | `references/sdks/powersync-kotlin.md` |
67| Swift | `references/sdks/powersync-swift.md` |
68
69## Key Rules to Apply Without Being Asked
70
71- Never define the `id` column in a PowerSync table schema; it is created automatically.
72- Use `column.integer` for booleans and `column.text` for ISO date strings.
73- `connect()` is fire-and-forget. Use `waitForFirstSync()` if you need readiness.
74- `transaction.complete()` is mandatory or the upload queue stalls permanently.
75- `disconnectAndClear()` is required on logout or user switch when local data must be wiped.
76- A 4xx response from `uploadData` blocks the upload queue permanently; return 2xx for validation errors.
aibot88