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

[KyleAMathews]

Summary

Adds @electric-sql/agent - 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/agent install.

Approach

Architecture

The skills system has three components:

1. Router skill (electric) - Lightweight overview that agents load first, explains what Electric is and what help is available
2. Deep skills - Detailed guidance for specific tasks (quickstart, TanStack integration, security, deployment, production)
3. 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/agent install          # Install to project
npx @electric-sql/agent install --global # Install to ~/.claude/skills etc.
npx @electric-sql/agent list-skills      # List available skills
npx @electric-sql/agent read-skill <name> # Output full skill content

Skills Included

@electric-sql/agent:

• 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

CI Automation

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

Key Invariants

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

Non-goals

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

Verification

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

# Test CLI
node dist/cli/index.js list-skills
node dist/cli/index.js read-skill electric

# Test install (with local skills dir)
ELECTRIC_AGENT_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/agent/ - 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

[coderabbitai]

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]

Open in StackBlitz

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: 992f91d

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.36%. Comparing base (ba6dd2c) to head (992f91d).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3775   +/-   ##
=======================================
  Coverage   87.36%   87.36%           
=======================================
  Files          23       23           
  Lines        2011     2011           
  Branches      528      533    +5     
=======================================
  Hits         1757     1757           
  Misses        252      252           
  Partials        2        2           

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.47% <ø> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	87.36% <ø> (ø)
unit-tests	87.36% <ø> (ø)

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.