docs: added SKILL.md to the documentation #3763
Conversation
📝 WalkthroughWalkthroughNew SKILL.md documentation file introduced detailing the ElectricSQL and TanStack DB integration pattern, architecture, security rules, and usage patterns. agents.md updated to reference both AGENTS.md and SKILL.md as part of an expanded agent instruction and skills framework with examples and resources. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
This PR adds documentation for SKILL.md alongside the existing AGENTS.md documentation, expanding the agents.md page to cover both agent instruction formats. The author notes this is a low-priority, largely LLM-generated PR intended to support the use of modular agent skills with Electric.
Changes:
- Updated page title and description to cover both AGENTS.md and SKILL.md
- Added new SKILL.md section with usage instructions, format explanation, and file inclusion
- Expanded "More information" section to reference agent skills resources
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <<< @/../SKILL.md | ||
|
|
There was a problem hiding this comment.
The documentation references a SKILL.md file that does not exist in the repository. This file inclusion directive will fail when the documentation is built. The SKILL.md file needs to be created in the repository root (alongside AGENTS.md) before this documentation can be merged, or this entire section should be removed until the file is ready.
| <<< @/../SKILL.md |
|
|
||
| ### Using Electric with agent skills | ||
|
|
||
| Electric provides a SKILL.md at [https://electric-sql.com/SKILL.md](/SKILL.md){target="_self"}. |
There was a problem hiding this comment.
This link references /SKILL.md which does not exist in the repository. The link will be broken until the SKILL.md file is created in the repository root.
|
|
||
| ### File contents | ||
|
|
||
| Copy our [`SKILL.md`](/SKILL.md){target="_self"} file to the root of your repo or package. Edit it and / or combine with your other project-specific skills, as you see fit. |
There was a problem hiding this comment.
This link references /SKILL.md which does not exist in the repository. The link will be broken until the SKILL.md file is created in the repository root.
| Documentation for guiding coding agents to develop apps with Electric. | ||
| outline: [2, 3] | ||
| Documentation for guiding coding agents and loading agent skills to develop apps with Electric. | ||
| outline: [2, 3, 4] |
There was a problem hiding this comment.
The outline was changed from [2, 3] to [2, 3, 4], but there are no H4 (####) headings in this document. The outline should remain [2, 3] to match the actual heading levels used (H2 and H3 only).
| outline: [2, 3, 4] | |
| outline: [2, 3] |
| claude "Load the Electric skill. Help me set up local-first sync with conflict resolution." | ||
| ``` | ||
|
|
||
| ### What are agent skills? |
There was a problem hiding this comment.
The heading hierarchy may be inconsistent. "What are agent skills?" at H3 level appears to be providing background information rather than being a subsection of "Using Electric with agent skills". Consider restructuring: either promote it to H2 level to sit alongside the other H2 sections, or reorganize the content flow so the hierarchy makes more semantic sense.
| ### What are agent skills? | |
| **What are agent skills?** |
|
|
||
| Electric provides a SKILL.md at [https://electric-sql.com/SKILL.md](/SKILL.md){target="_self"}. | ||
|
|
||
| SKILL.md is an [open format](https://agentskills.io) for defining modular, reusable capabilities that AI coding agents can load on-demand. Unlike AGENTS.md which provides general project instructions, a skill encapsulates specific procedural knowledge, SDK patterns, and best practices for targeted tasks. |
There was a problem hiding this comment.
The PR description mentions "opencode skills docs" at opencode.ai/docs/skills/, but the documentation links to agentskills.io as the reference for the skill format. These appear to be different resources. Verify that agentskills.io is the correct and authoritative reference for the SKILL.md format, or update the link if a different reference is more appropriate.
| SKILL.md is an [open format](https://agentskills.io) for defining modular, reusable capabilities that AI coding agents can load on-demand. Unlike AGENTS.md which provides general project instructions, a skill encapsulates specific procedural knowledge, SDK patterns, and best practices for targeted tasks. | |
| SKILL.md is an [open format](https://opencode.ai/docs/skills/) for defining modular, reusable capabilities that AI coding agents can load on-demand. Unlike AGENTS.md which provides general project instructions, a skill encapsulates specific procedural knowledge, SDK patterns, and best practices for targeted tasks. |
| description: >- | ||
| Documentation for guiding coding agents to develop apps with Electric. | ||
| outline: [2, 3] | ||
| Documentation for guiding coding agents and loading agent skills to develop apps with Electric. |
There was a problem hiding this comment.
The description "Documentation for guiding coding agents and loading agent skills" is slightly awkward. Consider revising to something clearer like "Documentation for guiding AI coding agents with instructions and skills when developing apps with Electric" or "Documentation for using AGENTS.md instructions and SKILL.md capabilities with AI coding agents".
| Documentation for guiding coding agents and loading agent skills to develop apps with Electric. | |
| Documentation for using AGENTS.md instructions and SKILL.md capabilities with AI coding agents when developing apps with Electric. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@SKILL.md`:
- Around line 369-388: The reference definitions in the "References" section are
malformed (they use "[n] URL") causing broken links and lint warnings; update
each reference to the proper Markdown reference-definition format "[n]: URL" for
all numbered entries (e.g., change "[1]
https://electric-sql.com/docs/api/http.md" to "[1]:
https://electric-sql.com/docs/api/http.md") so the [1]..[18] link labels resolve
correctly in SKILL.md's References block.
- Around line 40-42: Update the combined Markdown reference `[10][4]` so each
citation is explicit and renders separately (e.g., change to `[10] [4]` or
`[10], [4]`) in SKILL.md; locate the sentence "Violation of any rule = security
bug. See: Electric security & auth guides [10][4]." and replace the combined
reference with two distinct reference links `[10]` and `[4]` (or `[10], [4]`) so
each points to its own bibliography entry.
In `@website/docs/agents.md`:
- Around line 8-10: The product icon image tag (<img src="/img/icons/llms.svg"
class="product-icon" style="width: 72px" />) is missing alt text; add a
descriptive alt attribute (for example alt="LLMs icon" or a more specific
description like alt="Large language models icon") to the <img> element so
screen readers and accessibility tools can convey the image purpose.
🧹 Nitpick comments (1)
SKILL.md (1)
45-60: Add a language to the architecture fenced block.
The diagram fence is missing a language hint;text(orplain) keeps it readable and satisfies lint.✅ Suggested edit
-``` +```text Client (TanStack DB) ├─ Live Queries ├─ Optimistic Mutations ↓ ... Postgres (logical replication)
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
SKILL.mdwebsite/docs/agents.md
🧰 Additional context used
🧠 Learnings (10)
📚 Learning: 2026-01-14T14:45:05.855Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:05.855Z
Learning: Avoid old Electric patterns (bidirectional SQLite sync, `electrify()` API) – use Electric HTTP streaming with TanStack DB collections instead
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/**/*.{ts,tsx} : All reads from the Postgres database must be done via the Electric sync engine, not tRPC
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/src/lib/collections.ts : Use TanStack DB with Electric Sync Collections for client-side data management
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/**/*.{ts,tsx} : NEVER use tRPC for data reads - only use Electric SQL and useLiveQuery
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:05.855Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:05.855Z
Learning: Applies to **/{components,hooks,pages}/**/*.{ts,tsx} : Live queries use TanStack DB SQL-like syntax with support for `where`, `orderBy`, `limit`, `join`, `groupBy`, and `select` operators
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/src/**/*.server.{ts,tsx} : Use Drizzle ORM with PostgreSQL dialect for server-side database access with schema-first approach
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:05.855Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:05.855Z
Learning: Keep Electric and TanStack packages up-to-date: check npm for latest `electric-sql/*` and `tanstack/*-db` versions
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/**/*.{ts,tsx} : NEVER use TanStack Query - use TanStack DB instead
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/src/lib/collections.ts : Sync normalized data from tables into TanStack DB collections in the client and then write client-side queries for displaying data in components
Applied to files:
SKILL.md
📚 Learning: 2026-01-14T14:45:20.892Z
Learnt from: CR
Repo: electric-sql/electric PR: 0
File: examples/tanstack-db-web-starter/AGENTS.md:0-0
Timestamp: 2026-01-14T14:45:20.892Z
Learning: Applies to examples/tanstack-db-web-starter/src/lib/trpc/**/*.ts : Generate transaction IDs using `pg_current_xact_id()::xid::text` for Electric sync compatibility
Applied to files:
SKILL.md
🪛 markdownlint-cli2 (0.18.1)
website/docs/agents.md
8-8: Images should have alternate text (alt text)
(MD045, no-alt-text)
SKILL.md
41-41: Reference links and images should use a label that is defined
Missing link or image reference definition: "4"
(MD052, reference-links-images)
47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
63-63: Reference links and images should use a label that is defined
Missing link or image reference definition: "15"
(MD052, reference-links-images)
82-82: Reference links and images should use a label that is defined
Missing link or image reference definition: "15"
(MD052, reference-links-images)
210-210: Reference links and images should use a label that is defined
Missing link or image reference definition: "6"
(MD052, reference-links-images)
230-230: Reference links and images should use a label that is defined
Missing link or image reference definition: "7"
(MD052, reference-links-images)
260-260: Reference links and images should use a label that is defined
Missing link or image reference definition: "17"
(MD052, reference-links-images)
311-311: Reference links and images should use a label that is defined
Missing link or image reference definition: "9"
(MD052, reference-links-images)
351-351: Reference links and images should use a label that is defined
Missing link or image reference definition: "15"
(MD052, reference-links-images)
371-371: Bare URL used
(MD034, no-bare-urls)
372-372: Bare URL used
(MD034, no-bare-urls)
373-373: Bare URL used
(MD034, no-bare-urls)
374-374: Bare URL used
(MD034, no-bare-urls)
375-375: Bare URL used
(MD034, no-bare-urls)
376-376: Bare URL used
(MD034, no-bare-urls)
377-377: Bare URL used
(MD034, no-bare-urls)
378-378: Bare URL used
(MD034, no-bare-urls)
379-379: Bare URL used
(MD034, no-bare-urls)
380-380: Bare URL used
(MD034, no-bare-urls)
381-381: Bare URL used
(MD034, no-bare-urls)
382-382: Bare URL used
(MD034, no-bare-urls)
383-383: Bare URL used
(MD034, no-bare-urls)
384-384: Bare URL used
(MD034, no-bare-urls)
385-385: Bare URL used
(MD034, no-bare-urls)
386-386: Bare URL used
(MD034, no-bare-urls)
387-387: Bare URL used
(MD034, no-bare-urls)
388-388: Bare URL used
(MD034, no-bare-urls)
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| Violation of any rule = security bug. | ||
| See: Electric security & auth guides [10][4]. | ||
|
|
There was a problem hiding this comment.
Fix combined reference syntax and make refs explicit.
[10][4] renders as a single link with text “10” and currently points to ref 4, which is not the intent. Prefer separate refs like [10] and [4] (or [10], [4]) for clarity and correct rendering.
✅ Suggested edit
-See: Electric security & auth guides [10][4].
+See: Electric security & auth guides [10] and [4].📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Violation of any rule = security bug. | |
| See: Electric security & auth guides [10][4]. | |
| Violation of any rule = security bug. | |
| See: Electric security & auth guides [10] and [4]. | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
41-41: Reference links and images should use a label that is defined
Missing link or image reference definition: "4"
(MD052, reference-links-images)
🤖 Prompt for AI Agents
In `@SKILL.md` around lines 40 - 42, Update the combined Markdown reference
`[10][4]` so each citation is explicit and renders separately (e.g., change to
`[10] [4]` or `[10], [4]`) in SKILL.md; locate the sentence "Violation of any
rule = security bug. See: Electric security & auth guides [10][4]." and replace
the combined reference with two distinct reference links `[10]` and `[4]` (or
`[10], [4]`) so each points to its own bibliography entry.
| ## References | ||
| [1] https://electric-sql.com/docs/api/http.md | ||
| [2] https://tanstack.com/db/latest/docs/overview.md | ||
| [3] https://tanstack.com/db/latest/docs/collections/electric-collection.md | ||
| [4] https://electric-sql.com/docs/guides/auth.md | ||
| [5] https://electric-sql.com/docs/quickstart.md | ||
| [6] https://electric-sql.com/docs/guides/shapes.md | ||
| [7] https://tanstack.com/db/latest/docs/guides/live-queries.md | ||
| [8] https://electric-sql.com/blog/2024/11/21/local-first-with-your-existing-api.md | ||
| [9] https://electric-sql.com/docs/api/clients/typescript.md | ||
| [10] https://electric-sql.com/docs/guides/security.md | ||
| [11] https://electric-sql.com/product/cloud.md | ||
| [12] https://tanstack.com/db/latest/docs/collections/query-collection.md | ||
| [13] https://tanstack.com/db/latest/docs/guides/error-handling.md | ||
| [14] https://electric-sql.com/docs/stacks.md | ||
| [15] https://electric-sql.com/blog/2025/07/29/local-first-sync-with-tanstack-db.md | ||
| [16] https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query.md | ||
| [17] https://frontendatscale.com/blog/tanstack-db/ | ||
| [18] https://electric-sql.com/docs/guides/troubleshooting.md#slow-shapes |
There was a problem hiding this comment.
Reference definitions are malformed and trigger broken links.
The list uses [n] URL, but reference definitions must be [n]: URL. This also fixes the bare‑URL lint warnings.
✅ Suggested fix (excerpt)
-[1] https://electric-sql.com/docs/api/http.md
-[2] https://tanstack.com/db/latest/docs/overview.md
+[1]: https://electric-sql.com/docs/api/http.md
+[2]: https://tanstack.com/db/latest/docs/overview.md
...
-[18] https://electric-sql.com/docs/guides/troubleshooting.md#slow-shapes
+[18]: https://electric-sql.com/docs/guides/troubleshooting.md#slow-shapes📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## References | |
| [1] https://electric-sql.com/docs/api/http.md | |
| [2] https://tanstack.com/db/latest/docs/overview.md | |
| [3] https://tanstack.com/db/latest/docs/collections/electric-collection.md | |
| [4] https://electric-sql.com/docs/guides/auth.md | |
| [5] https://electric-sql.com/docs/quickstart.md | |
| [6] https://electric-sql.com/docs/guides/shapes.md | |
| [7] https://tanstack.com/db/latest/docs/guides/live-queries.md | |
| [8] https://electric-sql.com/blog/2024/11/21/local-first-with-your-existing-api.md | |
| [9] https://electric-sql.com/docs/api/clients/typescript.md | |
| [10] https://electric-sql.com/docs/guides/security.md | |
| [11] https://electric-sql.com/product/cloud.md | |
| [12] https://tanstack.com/db/latest/docs/collections/query-collection.md | |
| [13] https://tanstack.com/db/latest/docs/guides/error-handling.md | |
| [14] https://electric-sql.com/docs/stacks.md | |
| [15] https://electric-sql.com/blog/2025/07/29/local-first-sync-with-tanstack-db.md | |
| [16] https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query.md | |
| [17] https://frontendatscale.com/blog/tanstack-db/ | |
| [18] https://electric-sql.com/docs/guides/troubleshooting.md#slow-shapes | |
| ## References | |
| [1]: https://electric-sql.com/docs/api/http.md | |
| [2]: https://tanstack.com/db/latest/docs/overview.md | |
| [3]: https://tanstack.com/db/latest/docs/collections/electric-collection.md | |
| [4]: https://electric-sql.com/docs/guides/auth.md | |
| [5]: https://electric-sql.com/docs/quickstart.md | |
| [6]: https://electric-sql.com/docs/guides/shapes.md | |
| [7]: https://tanstack.com/db/latest/docs/guides/live-queries.md | |
| [8]: https://electric-sql.com/blog/2024/11/21/local-first-with-your-existing-api.md | |
| [9]: https://electric-sql.com/docs/api/clients/typescript.md | |
| [10]: https://electric-sql.com/docs/guides/security.md | |
| [11]: https://electric-sql.com/product/cloud.md | |
| [12]: https://tanstack.com/db/latest/docs/collections/query-collection.md | |
| [13]: https://tanstack.com/db/latest/docs/guides/error-handling.md | |
| [14]: https://electric-sql.com/docs/stacks.md | |
| [15]: https://electric-sql.com/blog/2025/07/29/local-first-sync-with-tanstack-db.md | |
| [16]: https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query.md | |
| [17]: https://frontendatscale.com/blog/tanstack-db/ | |
| [18]: https://electric-sql.com/docs/guides/troubleshooting.md#slow-shapes |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
371-371: Bare URL used
(MD034, no-bare-urls)
372-372: Bare URL used
(MD034, no-bare-urls)
373-373: Bare URL used
(MD034, no-bare-urls)
374-374: Bare URL used
(MD034, no-bare-urls)
375-375: Bare URL used
(MD034, no-bare-urls)
376-376: Bare URL used
(MD034, no-bare-urls)
377-377: Bare URL used
(MD034, no-bare-urls)
378-378: Bare URL used
(MD034, no-bare-urls)
379-379: Bare URL used
(MD034, no-bare-urls)
380-380: Bare URL used
(MD034, no-bare-urls)
381-381: Bare URL used
(MD034, no-bare-urls)
382-382: Bare URL used
(MD034, no-bare-urls)
383-383: Bare URL used
(MD034, no-bare-urls)
384-384: Bare URL used
(MD034, no-bare-urls)
385-385: Bare URL used
(MD034, no-bare-urls)
386-386: Bare URL used
(MD034, no-bare-urls)
387-387: Bare URL used
(MD034, no-bare-urls)
388-388: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In `@SKILL.md` around lines 369 - 388, The reference definitions in the
"References" section are malformed (they use "[n] URL") causing broken links and
lint warnings; update each reference to the proper Markdown reference-definition
format "[n]: URL" for all numbered entries (e.g., change "[1]
https://electric-sql.com/docs/api/http.md" to "[1]:
https://electric-sql.com/docs/api/http.md") so the [1]..[18] link labels resolve
correctly in SKILL.md's References block.
| <img src="/img/icons/llms.svg" class="product-icon" | ||
| style="width: 72px" | ||
| /> |
There was a problem hiding this comment.
Add alt text to the product icon for accessibility.
✅ Suggested edit
-<img src="/img/icons/llms.svg" class="product-icon"
+<img src="/img/icons/llms.svg" class="product-icon" alt="LLM icon"
style="width: 72px"
/>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <img src="/img/icons/llms.svg" class="product-icon" | |
| style="width: 72px" | |
| /> | |
| <img src="/img/icons/llms.svg" class="product-icon" alt="LLM icon" | |
| style="width: 72px" | |
| /> |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
In `@website/docs/agents.md` around lines 8 - 10, The product icon image tag (<img
src="/img/icons/llms.svg" class="product-icon" style="width: 72px" />) is
missing alt text; add a descriptive alt attribute (for example alt="LLMs icon"
or a more specific description like alt="Large language models icon") to the
<img> element so screen readers and accessibility tools can convey the image
purpose.
1 participant
WARNING: low priority and mostly llm'd PR, close if not interested.
Hello all,
This was for my personal use, but then I decided to share it.
I converted the provided AGENTS.md file to a compatible SKILL.md file. I assume by now you all know what skills are, if not, check the opencode skills docs. It's almost an exact replica of AGENTS.md, with few tweaks to make it work with agents.
I then asked copilot to add it to the existing agents.md page, while following the exact same structure and not changing anything else; I assume someone else who's a better writer will improve the flow of the page. I also suspect in the future we might need a better directory full of different kinds of skills.
I provided copilot with the references to use.
Thanks.
copilot generated slop:
Documentation improvements:
agents.mddocumentation to cover bothAGENTS.mdandSKILL.md, clarifying their purposes and how they help AI coding agents work with Electric.SKILL.mdformat, its role in defining modular agent skills, and how agents can use it for on-demand procedural knowledge, SDK patterns, and troubleshooting.agentskills.ioandskills.sh.Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.