feat: add @electric-sql/playbook package with AI coding assistant skills by KyleAMathews · Pull Request #3775 · electric-sql/electric

KyleAMathews · 2026-01-26T23:46:00Z

Summary

Adds @electric-sql/playbook - a new package providing AI coding assistant skills for building local-first apps with Electric and TanStack DB. Also adds skills to @electric-sql/client.

User impact: AI coding assistants (Claude Code, Cursor, Copilot, etc.) can now get contextual guidance when building Electric apps via npx @electric-sql/playbook install.

Approach

Architecture

The skills system has three components:

Router skill (electric) - Lightweight overview that agents load first, explains what Electric is and what help is available
Deep skills - Detailed guidance for specific tasks (quickstart, TanStack integration, security, deployment, production)
Thin pointers - Installed to agent directories (.claude/skills/, .cursor/skills/, etc.) that reference the full skills in the npm package

CLI Commands

npx @electric-sql/playbook install          # Install to project
npx @electric-sql/playbook install --global # Install to ~/.claude/skills etc.
npx @electric-sql/playbook list             # List available skills
npx @electric-sql/playbook show <name>      # Output full skill content

Skills Included

@electric-sql/playbook:

electric - Router/overview skill
electric-quickstart - New project setup
electric-tanstack-integration - Collections, live queries, mutations
electric-security-check - Security audit checklist
electric-go-live - Production readiness
deploying-electric - Cloud/Docker/self-hosted deployment

@electric-sql/client:

electric-shapes - Shapes API reference
electric-auth - Auth patterns
electric-http-api - HTTP API reference

Related Playbooks

The Electric ecosystem has three playbook packages (each with list and show commands):

@electric-sql/playbook - Electric sync patterns (this PR)
@tanstack/db-playbook - TanStack DB patterns
@durable-streams/playbook - Durable Streams patterns

CI Automation

Added GitHub workflow that detects when source files change and comments on PRs if skills may need updating (staleness detection).

Key Invariants

Skills never expose secrets - all examples show proxy pattern with server-side secret injection
Router skill is the only installed pointer - it guides agents to load other skills as needed
Skills stay under 500 lines for token efficiency

Non-goals

Publishing skills for durable-streams (separate repo/PR)
Automatic skill updates on publish (manual review preferred)

Verification

# Build the package
cd packages/playbook && pnpm build

# Test CLI
node dist/cli/index.js list
node dist/cli/index.js show electric

# Test install (with local skills dir)
ELECTRIC_PLAYBOOK_SKILLS_DIR=./skills node dist/cli/index.js install --target /tmp/test-project

# Test staleness detection
echo "AGENTS.md" | node scripts/check-skill-staleness.mjs /dev/stdin

Files Changed

packages/playbook/ - New package with CLI and skills
packages/typescript-client/skills/ - Skills for the client package
packages/typescript-client/package.json - Added "skills" to files array
.github/workflows/skill-staleness.yml - CI for detecting stale skills
scripts/check-skill-staleness.mjs - Script to check which skills reference changed files
.changeset/add-agent-skills.md - Changeset for versioning

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- New package with CLI commands: install, list-skills, read-skill - Skills for Electric ecosystem: quickstart, TanStack integration, security, deployment, production - Skills added to @electric-sql/client: shapes, auth, http-api - CI workflow for detecting stale skills when source files change - Thin pointer system: only router skill installed, loads others as needed Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

coderabbitai · 2026-01-26T23:46:07Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🔍 Trigger a full review

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-01-26T23:47:30Z

Open in StackBlitz

npm i https://pkg.pr.new/@electric-sql/playbook@3775

npm i https://pkg.pr.new/@electric-sql/react@3775

npm i https://pkg.pr.new/@electric-sql/client@3775

npm i https://pkg.pr.new/@electric-sql/y-electric@3775

commit: e493003

codecov · 2026-01-26T23:48:41Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.36%. Comparing base (ba6dd2c) to head (e493003).
⚠️ Report is 21 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3775      +/-   ##
==========================================
- Coverage   87.36%   87.36%   -0.01%     
==========================================
  Files          23       23              
  Lines        2011     2050      +39     
  Branches      528      541      +13     
==========================================
+ Hits         1757     1791      +34     
- Misses        252      257       +5     
  Partials        2        2

Flag	Coverage Δ
packages/experimental	`87.73% <ø> (ø)`
packages/react-hooks	`86.48% <ø> (ø)`
packages/start	`82.83% <ø> (ø)`
packages/typescript-client	`93.29% <ø> (-0.19%)`	⬇️
packages/y-electric	`56.05% <ø> (ø)`
typescript	`87.36% <ø> (-0.01%)`	⬇️
unit-tests	`87.36% <ø> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- Add @types/node to @electric-sql/agent devDependencies - Format check-skill-staleness.mjs with prettier Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CI expects all packages to have a coverage script. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Router skill now shows the full ecosystem and how to load skills from: - @tanstack/db-skills (npx db-skills show) - @durable-streams/client (cat from node_modules) - @electric-sql/agent (npx read-skill) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

netlify · 2026-01-30T15:58:09Z

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	`aa8e20a`
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/697cd4b05c967200085921ad
😎 Deploy Preview	https://deploy-preview-3775--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

pnpm only symlinks direct dependencies to node_modules, so users who only have @durable-streams/state won't have the client symlinked. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Use list/show pattern instead of hardcoding skill names. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Per updated RFC, rename package and CLI commands: - Package: @electric-sql/agent → @electric-sql/playbook - Binary: electric-agent → electric-playbook - Commands: list-skills → list, read-skill → show - Env var: ELECTRIC_AGENT_SKILLS_DIR → ELECTRIC_PLAYBOOK_SKILLS_DIR Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- @tanstack/db-playbook - @durable-streams/playbook - @electric-sql/playbook Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copy-paste-ready TanStack Start + Electric setup including: - Prerequisites checklist (nitro, server.ts, etc.) - Complete proxy helper functions - SSR/SPA mode configuration with link to official docs - Troubleshooting section for common errors - File structure reference Based on user testing feedback that skills need to be "the working example, explained" not conceptual fragments. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Complete proxy implementation guide including: - Helper function pattern (prepareElectricUrl, proxyElectricRequest) - ELECTRIC_PROTOCOL_QUERY_PARAMS usage and why it matters - Headers to delete (content-encoding, content-length) - Headers to add (Vary for cache isolation) - Framework examples: TanStack Start, Next.js, Express, Hono - Electric Cloud auth (source_id, secret) - Anti-patterns section Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Replace deprecated @tanstack/react-start/server pattern with current createFileRoute + server.handlers pattern. Also adds Vary header for cache isolation and updates skill cross-references. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Documents the three pieces needed for TanStack Start SPA mode: 1. defaultSsr: false in createStart 2. shellComponent pattern in root route 3. nitro plugin for server routes Links to official TanStack Start SPA mode guide. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Router skill (electric) now has quick reference table of all skills - electric-security-check links to proxy and auth skills - electric-auth links to proxy and setup skills Helps agents discover related skills when only one is loaded. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

electric-tanstack-integration: - SSR-safe URL construction (typeof window check) - Timestamp parser for Date conversion - txid generation with ::xid cast (critical!) - drizzle-zod schema integration - localOnlyCollectionOptions for auth state tanstack-start-quickstart: - Docker compose with wal_level=logical - Caddy/HTTP2 setup for optimal performance - better-auth integration with TanStack Start - Protected routes pattern (_authenticated) - Environment variables reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Keep the critical txid generation pattern but remove drizzle-specific schema setup - that belongs in a separate drizzle skill. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Comprehensive guide covering: - Database connection setup with node-postgres - Schema definition patterns (identity columns, arrays, timestamps) - drizzle-zod integration for generating Zod schemas - Critical txid generation with ::xid cast for Electric sync - Migration workflow with drizzle-kit - Query patterns with user scoping - Type inference and null handling - Common patterns (soft deletes, optimistic locking) Includes security note about not leaking server schemas to client and updated syntax for Drizzle v1.0.0-beta.2+ array changes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Zod v4 support is being added but not fully stable yet. Recommend staying on Zod v3.25.x for now. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Based on user testing feedback: 1. SSR-safe URLs: Use `new URL(..., window.location.origin)` pattern - Relative URLs like '/api/todos' fail during SSR - Must construct full absolute URL 2. Collection preloading: Add `collection.preload()` in route loaders - Prevents flash of empty state - Ensures data ready before component renders 3. One route per table (security): Emphasize that each table needs its own API route with hardcoded table name - Server controls table, not client - Generic /api/shapes?table=X is a security hole Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Treat shape URLs like regular API calls - pass business logic arguments via query params or route params, and let the server map them to actual Electric shape queries. This maintains the security boundary where clients never control the shape directly. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Standardize on ELECTRIC_SOURCE_ID/ELECTRIC_SECRET (not SOURCE_*) - electric-shapes: Add security warning, partitioned tables, log modes, subset snapshots, offset=now - electric-http-api: Add security note, SSE keep-alive details, auto-fallback behavior, Caddy/Apache proxy configs - AGENTS.md: Change Docker image from :canary to :latest Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

github-actions · 2026-01-31T20:44:20Z

🤖 Agent Skills Staleness Check

Skills potentially affected by this PR

The following skills reference source files that were modified:

deploying-electric (@electric-sql/playbook)

Path: packages/playbook/skills/deploying-electric/SKILL.md
Modified sources:
- AGENTS.md

electric (@electric-sql/playbook)

Path: packages/playbook/skills/electric/SKILL.md
Modified sources:
- AGENTS.md

electric-go-live (@electric-sql/playbook)

Path: packages/playbook/skills/electric-go-live/SKILL.md
Modified sources:
- AGENTS.md

electric-quickstart (@electric-sql/playbook)

Path: packages/playbook/skills/electric-quickstart/SKILL.md
Modified sources:
- AGENTS.md

electric-security-check (@electric-sql/playbook)

Path: packages/playbook/skills/electric-security-check/SKILL.md
Modified sources:
- AGENTS.md

electric-tanstack-integration (@electric-sql/playbook)

Path: packages/playbook/skills/electric-tanstack-integration/SKILL.md
Modified sources:
- AGENTS.md

tanstack-start-quickstart (@electric-sql/playbook)

Path: packages/playbook/skills/tanstack-start-quickstart/SKILL.md
Modified sources:
- AGENTS.md

Action needed: Review these skills and update if necessary.
Run npx @electric-sql/playbook show <name> to view current content.

Without this, Electric won't accept unauthenticated requests in local development. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- README: Add grep tip for finding skills by keyword - README: Add missing tanstack-start-quickstart to skills table - electric-tanstack-integration: Add Common Errors table with solutions - electric-tanstack-integration: Add explicit SSR routing hint Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews · 2026-02-03T13:29:04Z

packages/playbook/skills/electric/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: electric
+description: Electric sync engine for Postgres - routes to appropriate skills for building local-first apps


for all electric stuff — not "local-first"

KyleAMathews and others added 2 commits January 26, 2026 16:39

chore: add changeset for agent skills package

fb07d40

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews and others added 3 commits January 26, 2026 16:51

fix: add @types/node and format script

5031c51

- Add @types/node to @electric-sql/agent devDependencies - Format check-skill-staleness.mjs with prettier Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: add coverage script to agent package

992f91d

CI expects all packages to have a coverage script. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews and others added 5 commits January 30, 2026 09:35

fix: clarify durable-streams client must be direct dependency

9ff597e

pnpm only symlinks direct dependencies to node_modules, so users who only have @durable-streams/state won't have the client symlinked. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: remove confusing pnpm comment

cc69b28

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: simplify TanStack DB skill loading instructions

8acaa4d

Use list/show pattern instead of hardcoding skill names. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: update router skill to use playbook naming for all packages

f1a73f7

- @tanstack/db-playbook - @durable-streams/playbook - @electric-sql/playbook Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews changed the title ~~feat: add @electric-sql/agent package with AI coding assistant skills~~ feat: add @electric-sql/playbook package with AI coding assistant skills Jan 30, 2026

KyleAMathews and others added 14 commits January 30, 2026 14:27

set version to 0.0.1

d69c131

ci: add playbook package to pkg-pr-new preview builds

f2e4317

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Remove drizzle-zod schema code from tanstack integration skill

2cbc164

Keep the critical txid generation pattern but remove drizzle-specific schema setup - that belongs in a separate drizzle skill. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add Zod v4 compatibility note to electric-drizzle skill

42e28e7

Zod v4 support is being added but not fully stable yet. Recommend staying on Zod v3.25.x for now. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews and others added 2 commits February 1, 2026 08:04

Add ELECTRIC_INSECURE: true to Docker compose dev example

8c47477

Without this, Electric won't accept unauthenticated requests in local development. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

KyleAMathews commented Feb 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add @electric-sql/playbook package with AI coding assistant skills#3775

feat: add @electric-sql/playbook package with AI coding assistant skills#3775
KyleAMathews wants to merge 26 commits intomainfrom
skillz

KyleAMathews commented Jan 26, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 26, 2026

Review skipped

Uh oh!

pkg-pr-new bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

netlify bot commented Jan 30, 2026

Uh oh!

github-actions bot commented Jan 31, 2026 •

edited

Loading

Uh oh!

KyleAMathews Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

KyleAMathews commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Approach

Architecture

CLI Commands

Skills Included

Related Playbooks

CI Automation

Key Invariants

Non-goals

Verification

Files Changed

Uh oh!

coderabbitai bot commented Jan 26, 2026

Review skipped

Uh oh!

pkg-pr-new bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

netlify bot commented Jan 30, 2026

✅ Deploy Preview for electric-next ready!

Uh oh!

github-actions bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Skills potentially affected by this PR

deploying-electric (@electric-sql/playbook)

electric (@electric-sql/playbook)

electric-go-live (@electric-sql/playbook)

electric-quickstart (@electric-sql/playbook)

electric-security-check (@electric-sql/playbook)

electric-tanstack-integration (@electric-sql/playbook)

tanstack-start-quickstart (@electric-sql/playbook)

Uh oh!

KyleAMathews Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

KyleAMathews commented Jan 26, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 26, 2026 •

edited

Loading

codecov bot commented Jan 26, 2026 •

edited

Loading

github-actions bot commented Jan 31, 2026 •

edited

Loading