electricsql — Claude Code skill: what it does, how to install
A skill that briefs your coding agent on ElectricSQL: streaming slices of Postgres to the client through Shapes, plus the proxy and write patterns around it.
MIT 109 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill electricsql -a claude-codeWhat electricsql does
ElectricSQL moves data one way — from Postgres to the client, in real time, with logical replication doing the work. The skill lays out how Shapes carve out a slice of a table: a where filter and a list of columns, so the browser doesn't carry the whole thing. It also covers ShapeStream and Shape in plain JS, the useShape hook for React, and the reconnects and 401 FetchError your onError callback has to survive. Deeper material sits in references/: Docker and Postgres setup, auth, write patterns, monitoring, error handling.
Writes never touch Electric. Your own API takes them and hands back a txid, then the confirmed state streams to every connected client. The skill walks that loop and the write strategies between an online-only app and one that writes through the database.
Setup has two hard requirements. Postgres has to run with wal_level=logical set, otherwise Electric simply won't come up. Production wants ELECTRIC_SECRET in the environment, and ELECTRIC_INSECURE=true is the local shortcut. Exposing the engine to the open internet is called out as a mistake; shapes belong behind a proxy that checks the token and injects the user's where clause.
What it helps with
- Stand up Electric in Docker against a Postgres instance with logical replication on
- Wire a
useShapehook that pulls one filtered slice of a table - Put an auth proxy in front of shapes so each user sees only their rows
- Return
txidfrom a write handler and confirm it back to the client - Pick a write strategy for a local-first app
Example prompts for the agent
- Set up ElectricSQL against my Postgres and run it in Docker
- Give me a
useShapefor theitemstable filtered tostatus='active' - Write the auth proxy that injects a
whereclause per user before the shape request
How to install electricsql
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill electricsql -a claude-code2Manually: put the files in place
~/.claude/skills/electricsql/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/electricsql/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill electricsql -a codex2Manually: put the files in place
.agents/skills/electricsql/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill electricsql -a cursor2Manually: put the files in place
.cursor/skills/electricsql/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/electricsql2Manually: put the files in place
.github/skills/electricsql/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill electricsql -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/electricsqlManually: put the files in place
.devin/skills/electricsql/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill electricsql -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about electricsql
How do I install electricsql in Claude Code?
Run npx skills add oakoss/agent-skills --skill electricsql -a claude-code. The skill file lands at ~/.claude/skills/electricsql/SKILL.md.
What does the electricsql skill do?
It tells your agent how ElectricSQL streams partial Postgres replicas through Shapes, covering the ShapeStream API, the useShape hook, where filtering, auth proxies and write strategies.
Does ElectricSQL handle writes?
No. It only syncs the read path; writes go through your own API, which returns a txid so Electric can confirm the change back to clients.
Source text
SKILL.md · MIT
---
name: electricsql
description: |
ElectricSQL real-time Postgres sync engine using Shapes for partial replication. Covers ShapeStream API, React hooks, where clause filtering, column selection, auth proxy patterns, and progressive write strategies from online-only to through-the-database.
Use when setting up ElectricSQL, configuring Postgres sync, implementing shape-based data loading, building auth proxies for shapes, or choosing write patterns for local-first apps with Electric.
license: MIT
metadata:
author: oakoss
version: '1.0'
source: 'https://electric-sql.com/docs'
user-invocable: false
---
# ElectricSQL
## Overview
ElectricSQL is a sync engine that streams partial replicas of Postgres data to local clients via Shapes. It handles the read path — syncing rows from Postgres to the client in real-time using logical replication. Writes flow back through your existing API; Electric syncs the confirmed state back to all connected clients.
**When to use:** Real-time sync from Postgres to client apps, local-first architectures needing live data from Postgres, replacing polling with streaming updates, apps using TanStack DB with Electric collections, multi-client collaborative apps backed by Postgres.
**When NOT to use:** Non-Postgres databases, apps needing client-to-server sync built into the engine (Electric handles reads only), simple REST CRUD with no real-time needs, apps that don't benefit from local data.
## Quick Reference
| Pattern | API / Approach | Key Points |
| ------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| Shape request | `GET /v1/shape?table=items&offset=-1` | Initial sync fetches full snapshot |
| Live updates | `?live=true&handle=...&offset=...` | Long-poll for real-time changes after initial sync |
| SSE streaming | `?live=true&live_sse=true` | Persistent Server-Sent Events connection |
| Where clause | `?where=status='active'` | SQL-style row filtering at the server |
| Parameterized where | `?where=user_id=$1¶ms[1]=abc` | SQL injection safe parameterized filtering |
| Column selection | `?columns=id,title,status` | Sync only needed columns to reduce bandwidth |
| Full replica | `?replica=full` | Complete row data on updates and deletes |
| Changes only | `?log=changes_only` | Skip initial snapshot, receive only new changes |
| ShapeStream (JS) | `new ShapeStream({ url, params: { table } })` | Low-level streaming client with auto-reconnect |
| Shape (JS) | `new Shape(stream)` | Materializes stream into a Map of current values |
| useShape (React) | `useShape({ url, params: { table } })` | React hook with loading/error states |
| Auth proxy | Route shapes through your API server | Validate tokens, inject where clauses per user |
| Docker setup | `docker run -e DATABASE_URL=... electricsql/electric` | Single container, needs `wal_level=logical` |
| Electric secret | `ELECTRIC_SECRET=key` env var | Required for production; `ELECTRIC_INSECURE=true` for dev |
## Common Mistakes
| Mistake | Correct Pattern |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| Exposing Electric directly to the internet | Put Electric behind an auth proxy that validates tokens |
| Forgetting `wal_level=logical` in Postgres config | Required for logical replication; Electric will not start without it |
| Using Electric for writes | Electric is read-path only; writes go through your API |
| Not returning `txid` from write handlers | Return `{ txid }` so Electric can confirm sync completion |
| Syncing entire tables to every client | Use where clauses and column selection for partial replication |
| Hardcoding shape URL in client code | Use a proxy endpoint that adds auth and where clauses server-side |
| Using `offset=-1` for every request | Use `offset=-1` only for initial sync; use returned offset after |
| Not handling `FetchError` 401 in ShapeStream | Use `onError` callback to refresh tokens and retry |
## Delegation
> If the `local-first` skill is available, delegate architecture decisions and sync engine comparison to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y`
> If the `tanstack-db` skill is available, delegate collection setup, live queries, and optimistic mutation patterns to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y`
> If the `tanstack-start` skill is available, delegate shape proxy implementation with server functions to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y`
- **Setup and deployment**: Use `Task` agent for Docker and Postgres configuration
- **Architecture review**: Use `Plan` agent for auth proxy and write pattern design
## References
- [Setup, Docker, and Postgres configuration](references/setup.md)
- [Shapes, ShapeStream, and React hooks](references/shapes-and-streams.md)
- [Authentication and security patterns](references/auth-and-security.md)
- [Write patterns from online to through-the-DB](references/write-patterns.md)
- [Observability and monitoring](references/monitoring.md)
- [Sync performance optimization](references/sync-performance.md)
- [Error handling, retry patterns, txid flow, and control messages](references/error-handling.md)
© oakoss · MIT · oakoss/agent-skills