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

.changeset/add-agent-skills.md

@@ -0,0 +1,6 @@
+---
+'@electric-sql/playbook': minor
+'@electric-sql/client': patch
+---
+
+Add `@electric-sql/playbook` package with AI coding assistant skills for building Electric apps. Includes CLI commands (`install`, `list`, `show`) and skills for quickstart, TanStack integration, security checks, deployment, and production readiness. Also adds skills directory to `@electric-sql/client` with shapes, auth, and HTTP API reference skills.

.github/workflows/pr.yml

@@ -6,6 +6,7 @@ on:
       - 'packages/typescript-client/**'
       - 'packages/react-hooks/**'
       - 'packages/y-electric/**'
+      - 'packages/playbook/**'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -37,6 +38,6 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Build Packages
-        run: pnpm --filter @electric-sql/client --filter @electric-sql/react --filter @electric-sql/y-electric run build
+        run: pnpm --filter @electric-sql/client --filter @electric-sql/react --filter @electric-sql/y-electric --filter @electric-sql/playbook run build
       - name: Publish Previews
-        run: pnpx pkg-pr-new publish --pnpm --compact './packages/typescript-client' './packages/react-hooks' './packages/y-electric'
+        run: pnpx pkg-pr-new publish --pnpm --compact './packages/typescript-client' './packages/react-hooks' './packages/y-electric' './packages/playbook'

.github/workflows/skill-staleness.yml

@@ -0,0 +1,82 @@
+name: Skill Staleness Check
+
+on:
+  pull_request:
+    paths:
+      # Source files that skills reference
+      - 'AGENTS.md'
+      - 'website/docs/**/*.md'
+      - 'packages/typescript-client/src/**/*.ts'
+      # The skills themselves
+      - 'packages/agent/skills/**/*.md'
+      - 'packages/typescript-client/skills/**/*.md'
+
+jobs:
+  check-staleness:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Get changed files
+        id: changed-files
+        run: |
+          # Get the list of changed files
+          git diff --name-only origin/${{ github.base_ref }}...HEAD > changed-files.txt
+          echo "Changed files:"
+          cat changed-files.txt
+
+      - name: Check skill staleness
+        id: staleness
+        continue-on-error: true
+        run: |
+          exit_code=0
+          node scripts/check-skill-staleness.mjs changed-files.txt > staleness-report.txt 2>&1 || exit_code=$?
+          echo "exit_code=$exit_code" >> $GITHUB_OUTPUT
+
+      - name: Comment on PR
+        if: steps.staleness.outputs.exit_code == '1'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('staleness-report.txt', 'utf8');
+
+            // Check if we already commented
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(c =>
+              c.user.type === 'Bot' &&
+              c.body.includes('Skills potentially affected by this PR')
+            );
+
+            const body = `🤖 **Agent Skills Staleness Check**\n\n${report}`;
+
+            if (botComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body,
+              });
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

AGENTS.md

@@ -295,7 +295,7 @@ services:
     command: ['postgres', '-c', 'config_file=/etc/postgresql/postgresql.conf']
 
   backend:
-    image: electricsql/electric:canary
+    image: electricsql/electric:latest
     environment:
       DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
       ELECTRIC_INSECURE: true

packages/playbook/README.md

@@ -0,0 +1,79 @@
+# @electric-sql/playbook
+
+Electric Playbook - skills for building apps with [Electric](https://electric-sql.com).
+
+## Overview
+
+This package provides AI agent skills that help coding assistants (Claude, Cursor, Copilot, etc.) build local-first applications with Electric and TanStack DB.
+
+## Installation
+
+```bash
+npm install @electric-sql/playbook
+```
+
+## Usage
+
+### CLI Commands
+
+Install thin skill pointers to your agent's skills directory:
+
+```bash
+npx @electric-sql/playbook install
+```
+
+Install globally (to `~/.claude/skills`, etc.):
+
+```bash
+npx @electric-sql/playbook install --global
+```
+
+List available skills:
+
+```bash
+npx @electric-sql/playbook list
+```
+
+Output the full content of a skill:
+
+```bash
+npx @electric-sql/playbook show electric
+```
+
+### Finding Skills by Keyword
+
+When you don't know the exact skill name, grep the installed package:
+
+```bash
+# Search for skills mentioning a keyword
+grep -r "SSR" node_modules/@electric-sql/playbook/skills/
+
+# Find all skill files
+find node_modules -name "SKILL.md" -path "*playbook*"
+```
+
+### Skills
+
+This package includes the following skills:
+
+| Skill                           | Description                                               |
+| ------------------------------- | --------------------------------------------------------- |
+| `electric`                      | Router skill - Electric ecosystem overview and navigation |
+| `electric-quickstart`           | Getting started with Electric + TanStack DB               |
+| `tanstack-start-quickstart`     | Complete TanStack Start + Electric setup (SSR config)     |
+| `electric-tanstack-integration` | Deep integration patterns for Electric with TanStack DB   |
+| `electric-security-check`       | Security audit checklist for Electric apps                |
+| `electric-go-live`              | Production readiness checklist                            |
+| `deploying-electric`            | Deployment patterns (Cloud, Docker, self-hosted)          |
+
+Additional skills are available in other Electric packages:
+
+- `@electric-sql/client` - `electric-shapes`, `electric-auth`, `electric-http-api`
+
+## How It Works
+
+Skills are markdown files with YAML frontmatter that provide context and instructions to AI coding assistants. When installed, thin pointers are created in your agent's skills directory that reference the full skill content in the npm package.
+
+## License
+
+Apache-2.0

packages/playbook/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@electric-sql/playbook",
+  "version": "0.0.2",
+  "description": "Electric Playbook - skills for building apps with Electric",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "ElectricSQL team and contributors.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/electric-sql/electric.git",
+    "directory": "packages/playbook"
+  },
+  "bugs": {
+    "url": "https://github.com/electric-sql/electric/issues"
+  },
+  "homepage": "https://electric-sql.com",
+  "bin": {
+    "electric-playbook": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./skills/*": "./skills/*",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "coverage": "echo 'No tests yet'",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.5.2"
+  }
+}