feat: add playbook skills for AI coding agents by KyleAMathews · Pull Request #1293 · TanStack/db

KyleAMathews · 2026-02-24T22:57:09Z

Add SKILL.md files to 6 packages so AI coding agents can discover and use TanStack DB correctly. Skills ship inside each npm package — agents read them directly from node_modules.

Approach

Generated using skill-tree-generator v2.0 from the domain map and skill spec produced by skill-domain-discovery. The skill tree is split into two layers:

Core skills (ship with @tanstack/db) — framework-agnostic: collection setup, query builder, mutations/optimistic state, sync/connectivity
Framework skills (ship with each adapter) — React hooks, Vue composables, Svelte runes, Solid signals, Angular inject

Skills live inside each package directory (not a central skills/ folder) so they ship with npm publish. Each package.json gets "skills" added to its files array.

Key invariants

Every code example uses real imports with exact package names
Every Common Mistake is silent (not an obvious compile error), library-specific, and sourced to docs or source code
Core skills contain zero framework-specific code
Framework skills declare requires: db-core so agents load core concepts first
All 33 failure modes from domain discovery are covered

Non-goals

No references/ overflow files — all skills stayed under 500 lines
No composition skills (Router integration, etc.) — deferred to follow-up
No security/go-live skills — TanStack DB doesn't have server-side surface area

Files changed

File	What
`packages/db/skills/db-core/SKILL.md`	Router — overview + sub-skill registry
`packages/db/skills/db-core/collection-setup/SKILL.md`	Collection creation, adapters, schemas (7 mistakes)
`packages/db/skills/db-core/live-queries/SKILL.md`	Query builder, operators, joins, aggregations (8 mistakes)
`packages/db/skills/db-core/mutations-optimistic/SKILL.md`	Mutations, transactions, optimistic actions (8 mistakes)
`packages/db/skills/db-core/sync-connectivity/SKILL.md`	Sync modes, Electric txid, custom adapters (6 mistakes)
`packages/react-db/skills/react-db/SKILL.md`	useLiveQuery, Suspense, infinite queries (2 mistakes)
`packages/vue-db/skills/vue-db/SKILL.md`	useLiveQuery composable with refs
`packages/svelte-db/skills/svelte-db/SKILL.md`	Svelte 5 runes, destructuring warning (2 mistakes)
`packages/solid-db/skills/solid-db/SKILL.md`	Signal tracking inside query fn (1 mistake)
`packages/angular-db/skills/angular-db/SKILL.md`	injectLiveQuery with signal params
`packages/*/package.json`	Add `"skills"` to `files` array (6 packages)

Verification

# Verify skills are included in npm tarball
cd packages/db && pnpm pack --dry-run | grep skills
cd packages/react-db && pnpm pack --dry-run | grep skills

Feedback

Review posted to TanStack/playbooks#3 (comment) with spec gaps and suggestions for skill-tree-generator v2.1.

🤖 Generated with Claude Code

Add SKILL.md files to each package so AI coding agents can discover and use TanStack DB correctly. Core skills (collection setup, live queries, mutations, sync) ship with @tanstack/db. Framework-specific skills ship with each adapter package. Covers 33 validated failure modes across 10 skill files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

changeset-bot · 2026-02-24T22:57:13Z

🦋 Changeset detected

Latest commit: a3f3677

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@tanstack/db	Patch
@tanstack/react-db	Patch
@tanstack/vue-db	Patch
@tanstack/svelte-db	Patch
@tanstack/solid-db	Patch
@tanstack/angular-db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/offline-transactions	Patch
@tanstack/powersync-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/trailbase-db-collection	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-02-24T23:00:27Z

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1293

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1293

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1293

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1293

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1293

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1293

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1293

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1293

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1293

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1293

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1293

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1293

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1293

commit: a3f3677

github-actions · 2026-02-24T23:01:02Z

Size Change: 0 B

Total Size: 92.6 kB

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/collection/change-events.js`	1.39 kB
`./packages/db/dist/esm/collection/changes.js`	1.22 kB
`./packages/db/dist/esm/collection/events.js`	388 B
`./packages/db/dist/esm/collection/index.js`	3.32 kB
`./packages/db/dist/esm/collection/indexes.js`	1.1 kB
`./packages/db/dist/esm/collection/lifecycle.js`	1.75 kB
`./packages/db/dist/esm/collection/mutations.js`	2.34 kB
`./packages/db/dist/esm/collection/state.js`	3.49 kB
`./packages/db/dist/esm/collection/subscription.js`	3.71 kB
`./packages/db/dist/esm/collection/sync.js`	2.41 kB
`./packages/db/dist/esm/deferred.js`	207 B
`./packages/db/dist/esm/errors.js`	4.7 kB
`./packages/db/dist/esm/event-emitter.js`	748 B
`./packages/db/dist/esm/index.js`	2.69 kB
`./packages/db/dist/esm/indexes/auto-index.js`	742 B
`./packages/db/dist/esm/indexes/base-index.js`	766 B
`./packages/db/dist/esm/indexes/btree-index.js`	2.17 kB
`./packages/db/dist/esm/indexes/lazy-index.js`	1.1 kB
`./packages/db/dist/esm/indexes/reverse-index.js`	538 B
`./packages/db/dist/esm/local-only.js`	808 B
`./packages/db/dist/esm/local-storage.js`	2.1 kB
`./packages/db/dist/esm/optimistic-action.js`	359 B
`./packages/db/dist/esm/paced-mutations.js`	496 B
`./packages/db/dist/esm/proxy.js`	3.75 kB
`./packages/db/dist/esm/query/builder/functions.js`	733 B
`./packages/db/dist/esm/query/builder/index.js`	4.09 kB
`./packages/db/dist/esm/query/builder/ref-proxy.js`	1.05 kB
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.43 kB
`./packages/db/dist/esm/query/compiler/expressions.js`	430 B
`./packages/db/dist/esm/query/compiler/group-by.js`	2.23 kB
`./packages/db/dist/esm/query/compiler/index.js`	2.04 kB
`./packages/db/dist/esm/query/compiler/joins.js`	2.11 kB
`./packages/db/dist/esm/query/compiler/order-by.js`	1.45 kB
`./packages/db/dist/esm/query/compiler/select.js`	1.09 kB
`./packages/db/dist/esm/query/expression-helpers.js`	1.43 kB
`./packages/db/dist/esm/query/ir.js`	673 B
`./packages/db/dist/esm/query/live-query-collection.js`	360 B
`./packages/db/dist/esm/query/live/collection-config-builder.js`	5.55 kB
`./packages/db/dist/esm/query/live/collection-registry.js`	264 B
`./packages/db/dist/esm/query/live/collection-subscriber.js`	2.42 kB
`./packages/db/dist/esm/query/live/internal.js`	145 B
`./packages/db/dist/esm/query/optimizer.js`	2.62 kB
`./packages/db/dist/esm/query/predicate-utils.js`	2.97 kB
`./packages/db/dist/esm/query/subset-dedupe.js`	921 B
`./packages/db/dist/esm/scheduler.js`	1.3 kB
`./packages/db/dist/esm/SortedMap.js`	1.3 kB
`./packages/db/dist/esm/strategies/debounceStrategy.js`	247 B
`./packages/db/dist/esm/strategies/queueStrategy.js`	428 B
`./packages/db/dist/esm/strategies/throttleStrategy.js`	246 B
`./packages/db/dist/esm/transactions.js`	2.9 kB
`./packages/db/dist/esm/utils.js`	924 B
`./packages/db/dist/esm/utils/browser-polyfills.js`	304 B
`./packages/db/dist/esm/utils/btree.js`	5.61 kB
`./packages/db/dist/esm/utils/comparison.js`	952 B
`./packages/db/dist/esm/utils/cursor.js`	457 B
`./packages/db/dist/esm/utils/index-optimization.js`	1.51 kB
`./packages/db/dist/esm/utils/type-guards.js`	157 B

_{compressed-size-action::db-package-size}

github-actions · 2026-02-24T23:01:37Z

Size Change: 0 B

Total Size: 3.7 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	225 B
`./packages/react-db/dist/esm/useLiveInfiniteQuery.js`	1.17 kB
`./packages/react-db/dist/esm/useLiveQuery.js`	1.34 kB
`./packages/react-db/dist/esm/useLiveSuspenseQuery.js`	559 B
`./packages/react-db/dist/esm/usePacedMutations.js`	401 B

_{compressed-size-action::react-db-package-size}

- Add missing `and` import to code examples across 6 framework skills - Remove nonexistent `ne` operator from live-queries frontmatter - Add Svelte destructuring reactivity warning (HIGH priority mistake) - Add `isIdle` and `isCleanedUp` to Vue and Angular return shape docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

The existing skill only covered `===`. Now explicitly shows all three wrong forms: bare property refs (todo.completed), negation (!todo.completed), and comparison (todo.completed === false). Explains the isExpressionLike() validation mechanism. Addresses #1297. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reference files provide agents with deep API documentation that exceeds what fits in a single SKILL.md: - Per-adapter configs (Electric, Query, PowerSync, RxDB, TrailBase) - Full query operator reference (comparison, logical, aggregate, string, math) - Schema validation deep-dive (TInput/TOutput, transforms, defaults, errors) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Every code sample was verified against the actual documentation, example code, and source. Key fixes: - Electric: handlers call API endpoints, not raw SQL. Txid generation is server-side code. Added all three sync strategies (txid return, awaitMatch, simple timeout). Fixed pg_current_xact_id casting (::xid::text not ::text). - Query: fixed import from @tanstack/query-core (not react-query). Added expression helpers, queryOptions interop. - PowerSync: imports from @powersync/web per docs. Added all 4 option patterns. Added required onDeserializationError. - RxDB: imports from rxdb/plugins/core per docs. Added title field, startSync option, replication example. - TrailBase: fixed initClient() (not new Client()). Unix timestamps (not ISO strings). id is required. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

ci: apply automated fixes

113f3b5

KyleAMathews and others added 9 commits February 24, 2026 16:17

ci: apply automated fixes

3975c77

chore: add changeset for playbook skills

5139771

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

ci: apply automated fixes

1c30ae2

style: run prettier on sync-connectivity skill files

9f4bfb6

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

chore: add prettier for markdown files to lint-staged

a3f3677

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add playbook skills for AI coding agents#1293

feat: add playbook skills for AI coding agents#1293
KyleAMathews wants to merge 11 commits intomainfrom
feat/playbook-skills

KyleAMathews commented Feb 24, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 24, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

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

Uh oh!

Approach

Key invariants

Non-goals

Files changed

Verification

Feedback

Uh oh!

changeset-bot bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

KyleAMathews commented Feb 24, 2026 •

edited

Loading

changeset-bot bot commented Feb 24, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 24, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading