Skip to content

Commit 5a3fb3b

Browse files
michaelbarnesbean1352khawarizmusjoshuabrink
authored
First release of PowerSync Agent Skills (#6)
* added the first attempt at PowerSync skills, including: powersync-js, powersync-debug, powersync-service and SKILL files. starting with js SDK and will expand from there. * added new sync-streams page and updated SKILL.md. updated README.md with install section and usage examples. corrections in other references. this branch has URLs that point to a local copy of the sync-streams-beta branch of powersync/docs, allowing me to test the skills using the up and coming sync streams beta * fixed some grammar and added missing bullet points * fixed typo * added a new row for the Swift SDK reference in SKILL.md. minor changes to the sync-streams.md reference. added a new powersync-swift.md reference. * fixed spelling and added additional resources for the Swift reference * added new powersync-debug.md which contains common issues developers run into and focuses on the most common issues seen in the last 3 months. added supported platforms for the swift reference. fixed a few things in powersync-service around passwords with specific instructions for agents around passwords * updated skill name. added an overview reference. updated the debug reference with better replication lag instructions. refactored the powersync-service reference. added legacy wording for sync rules. * Added .claude-plugin, CLAUDE.md, AGENTS.md and updated SKILL.md * updated the npx command * fixed actual command * changed the language in the SDK references * Added to powersync-js skill with additional resources, updated schema definition examples, and clarified backend integration instructions. (#2) Co-authored-by: bean1352 <[email protected]> * added explicit VFS options. added placeholder files for the missing sdks (.net, kotlin and dart) * removed sync-rules.md and sync-streams.md, they are now combined in sync-config.md which matches the updated docs * added placeholder references for outstanding SDKs, updated the SDK references to match along with the README. also updates to SKILL.md to reference the new sync-config.md * added first version of the dart reference, updated some wording in the swift reference and added the TODO blurb for the kotlin reference * updated the directory structure and usage list in AGENTS.md. also removed the when to use section as the AGENTS.md details the need to first read SKILL.md which already contains the usage examples * removed supported sdks section in the readme * docs: update PowerSync architecture, PowerSync service, and sync rules references * fix: update link format for sync-config.md in PowerSync service documentation * fix: update links to use HTTPS in PowerSync service and Swift SDK documentation * fix: update links to use .md extension in PowerSync documentation for consistency * docs: enhance PowerSync SDK documentation with new JavaScript/TypeScript references for React, React Native, Vue, Node.js, and TanStack integrations; update AGENTS.md and SKILL.md for clarity and structure * removed text styling to help reduce token usage * feat: add initial kotlin and dotnet skills (#5) * minor changes based on some testing converting a supabase app to use PowerSync * initialized Claude and added Claude.md and fixed a few bugs such as invalid links and duplicate sync rule definitions * Updated entry point files to use less tokens and provide a clearer roadmap as to which references to use based on the task the agent works on * added formatter at the top of the files to be consistent with dotnet and kotlin * added annotations for internals section; Without the skip signal, agents load the full file including ~80 lines of QueryStore internals and op type enums that are irrelevant for standard integration work. Repeated across many sessions this is meaningful wasted context. * Updated Swift setup with numbered steps, removed example project links, replaced query table with code blocks. fixed truncated watch example. fixed sync streams link, removed requestLogger from connect(). added write example for GRDB * Added direct instructions to links in references tables to only use the links if the examples do not cover the specifics needs of the task * added cli reference. updated claude and skill.md to use the CLI as part of setup config. added numbered setup steps to the other sdks * added the new powersync docker related topics for local development * added CONTRIBUTING.md for developers to read when contributing. Added the dino image and updated gitignore * added contribution details, updated gitignore and the dino image * add Stream Options section and expand Client Usage in sync-config skill * add inline query patterns and parameter examples to sync-config skill * add Advanced Topics section to sync-config skill with references for specialized use cases * add "when to use TanStack DB" guidance to tanstack reference * Add attachments reference with mermaid flow diagram * Update sync-config documentation to correct link for sync-streams reference * fix link in sync-config.md to point to the correct section for sync-streams * Align skill metadata with Agent Skills spec and industry conventions (#9) * Changed Kotlin SDK naming from "Kotlin Multiplatform SDK" to "Kotlin SDK" * Fix relative paths and add CI (#10) * Fix relative paths in SKILL.md and AGENTS.md reference tables * Use skill-root-relative paths for all file references * Add validation script and CI workflow * Add validation script and CI workflow for skill validation * updated the cli reference with specific on the commands and usage for self-hosting * fixed expo go vs. native adapter wording * fixed a number of issues with supabase auth and added dedicated reference for it so agents do not use this reference when not working on supabase integrated apps * added some details on db requirements for supabase (publications) * added some details around publications * updated sync-dino.png with a few agent icons * updated license information --------- Co-authored-by: bean1352 <[email protected]> Co-authored-by: Amine <[email protected]> Co-authored-by: Al-Khawarizmi <[email protected]> Co-authored-by: Joshua Brink <[email protected]> Co-authored-by: Dean Braun <[email protected]>
1 parent e635340 commit 5a3fb3b

30 files changed

Lines changed: 6429 additions & 124 deletions

.claude-plugin/marketplace.json

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"name": "powersync-agent-skills",
3+
"owner": {
4+
"name": "PowerSync",
5+
"url": "https://github.com/powersync-ja/agent-skills",
6+
"email": "[email protected]"
7+
},
8+
"metadata": {
9+
"description": "Official PowerSync agent skills for Claude Code",
10+
"version": "1.0.0"
11+
},
12+
"plugins": [
13+
{
14+
"name": "powersync-skills",
15+
"description": "Agent skills that help developers build applications with PowerSync",
16+
"source": "./",
17+
"skills": ["./skills/powersync"],
18+
"version": "1.0.0",
19+
"author": {
20+
"name": "PowerSync"
21+
},
22+
"keywords": [
23+
"powersync",
24+
"offline-first",
25+
"local-first",
26+
"sync",
27+
"sqlite",
28+
"react-native",
29+
"flutter",
30+
"kotlin",
31+
"swift",
32+
"dotnet",
33+
"typescript"
34+
],
35+
"category": "integration",
36+
"license": "CC0-1.0"
37+
}
38+
]
39+
}

.github/workflows/validate.yml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Validate Skills
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
validate:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: 20
16+
- run: node scripts/validate.mjs
17+
18+
- name: Validate SKILL.md (Agent Skills spec)
19+
uses: Flash-Brew-Digital/validate-skill@v1
20+
with:
21+
path: ./skills/powersync
22+
validate-references: true
23+
fail-on-warning: true

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
.env
22
.DS_Store
3-
node_modules/
3+
node_modules/
4+
.claude

CLAUDE.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
This repository contains PowerSync Agent Skills — context files that teach AI coding agents how to build applications with [PowerSync](https://powersync.com). The skills follow the [Agent Skills](https://agentskills.io/) specification and are distributed via `skills.sh` or the Claude Code plugin marketplace.
8+
9+
There is no build step, test suite, or compiled output. The deliverable is the content of the markdown files themselves.
10+
11+
## Repository Structure
12+
13+
```
14+
skills/powersync/
15+
├── SKILL.md # Entrypoint — agent reads this first to understand when/how to use the skill
16+
├── AGENTS.md # Same content as SKILL.md; used by non-Claude agents (points to AGENTS.md)
17+
├── CLAUDE.md # Points Claude to AGENTS.md
18+
└── references/
19+
├── powersync-overview.md
20+
├── powersync-service.md
21+
├── powersync-debug.md
22+
├── sync-config.md
23+
└── sdks/
24+
├── powersync-js.md # JS/TS core — always load for any JS/TS project
25+
├── powersync-js-react.md # React web + Next.js
26+
├── powersync-js-react-native.md # React Native + Expo
27+
├── powersync-js-vue.md # Vue + Nuxt
28+
├── powersync-js-node.md # Node.js + Electron
29+
├── powersync-js-tanstack.md # TanStack Query + TanStack DB
30+
├── powersync-dart.md
31+
├── powersync-dotnet.md
32+
├── powersync-kotlin.md
33+
└── powersync-swift.md
34+
```
35+
36+
## How Skills Are Structured
37+
38+
**`SKILL.md`** is the agent entrypoint. It defines:
39+
- Frontmatter (`name`, `description`) used by the skills registry
40+
- When the skill applies (trigger conditions)
41+
- A reference table pointing to files in `references/`
42+
43+
**`references/`** contains the detailed knowledge. Each file is a standalone reference on a specific topic (SDK, service config, debugging, etc.).
44+
45+
**JS/TS SDK split**: The JS SDK is split across multiple files. `powersync-js.md` is always the base; framework files (`-react`, `-vue`, `-node`, etc.) are additive and do not repeat core content.
46+
47+
## Plugin Manifest
48+
49+
`.claude-plugin/marketplace.json` defines how the Claude Code marketplace discovers and loads the skill. The `source` and `skills` paths are relative to the repo root.
50+
51+
## Package Manager
52+
53+
This project uses **pnpm** (`[email protected]`). There are no scripts defined — `package.json` exists only for package metadata and registry purposes.
54+
55+
## Contributing New Skills or References
56+
57+
- New SDK references belong in `skills/powersync/references/sdks/`
58+
- New topic references belong in `skills/powersync/references/`
59+
- After adding a reference file, add an entry to the reference table in `SKILL.md` and `AGENTS.md`
60+
- Keep reference files focused on a single topic; avoid duplicating content across files

CONTRIBUTING.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Contributing to PowerSync Agent Skills
2+
3+
Contributions are welcome from the community — whether you're fixing a bug, improving an existing reference, or adding support for a new SDK or topic.
4+
5+
## What Lives Here
6+
7+
This repo contains a single skill (`skills/powersync/`) following the [Agent Skills](https://agentskills.io/) specification. The skill is a collection of Markdown reference files that agents load when helping developers build with PowerSync.
8+
9+
```
10+
skills/powersync/
11+
├── CLAUDE.md # Entry point for Claude Code
12+
├── AGENTS.md # Entry point for other agents (Cursor, Codex, etc.)
13+
├── SKILL.md # Entry point for skills.sh
14+
└── references/
15+
├── sync-config.md
16+
├── powersync-service.md
17+
├── powersync-debug.md
18+
├── powersync-overview.md
19+
├── powersync-cli.md
20+
└── sdks/
21+
├── powersync-js.md # Foundation for all JS/TS projects
22+
├── powersync-js-react.md
23+
├── powersync-js-react-native.md
24+
├── powersync-js-vue.md
25+
├── powersync-js-node.md
26+
├── powersync-js-tanstack.md
27+
├── powersync-dart.md
28+
├── powersync-dotnet.md
29+
├── powersync-kotlin.md
30+
└── powersync-swift.md
31+
```
32+
33+
## Types of Contributions
34+
35+
### Bug fixes
36+
- Broken or outdated links
37+
- Incorrect code examples
38+
- API changes in a PowerSync SDK release
39+
40+
### Reference improvements
41+
- Clearer explanations or examples for tricky patterns
42+
- Missing common use cases (queries, transactions, sync lifecycle)
43+
- Reducing token cost — replacing wide URL tables with inline explanations, removing rarely-needed content, adding skip signals to optional sections
44+
45+
### New SDK or framework coverage
46+
- A new framework file (e.g. `powersync-js-solidjs.md`) following the patterns of existing files
47+
- Additional patterns in an existing file (e.g. a new ORM integration)
48+
49+
### Entry point improvements
50+
- Routing table updates when a new reference file is added
51+
- New key rules that apply across all projects
52+
53+
## Writing Style
54+
55+
These files are read by agents, not humans. Write for clarity and token efficiency:
56+
57+
- **Prefer code over prose** — a working example communicates more than a paragraph of explanation.
58+
- **Use numbered setup steps** — agents orient faster with a clear 1–2–3 sequence.
59+
- **No filler** — skip marketing language, motivational intros, and redundant summaries.
60+
- **Signal optional sections** — if a section is only needed for edge cases or debugging, add a skip note: `> Load this section only when…`
61+
- **Resource table descriptions** — describe when to consult a link, not just what it is. Use the pattern: `"Full [X] guide, consult only when the inline examples don't cover your case."`
62+
63+
### File structure
64+
65+
Every reference file should have frontmatter:
66+
67+
```yaml
68+
---
69+
name: powersync-<topic>
70+
description: One-sentence description of what this file covers
71+
metadata:
72+
tags: comma, separated, trigger, keywords
73+
---
74+
```
75+
76+
Tags are used by skill routing systems for auto-activation. Use terms developers would type when asking for help: SDK names, API method names (`uploadData`, `fetchCredentials`), error terms, feature names.
77+
78+
### Key rules (apply to all files)
79+
80+
- Never define `id` in a PowerSync table schema — it is created automatically.
81+
- Use `column.integer` (0/1) for booleans and `column.text` (ISO string) for dates.
82+
- `connect()` is fire-and-forget — do not `await` it expecting data to be ready.
83+
- `transaction.complete()` must always be called or the upload queue stalls permanently.
84+
- `disconnectAndClear()` on logout, not `disconnect()`.
85+
- Backend must return 2xx for validation errors — a 4xx blocks the upload queue permanently.
86+
87+
If you add an example that touches these patterns, make sure it reflects these rules.
88+
89+
## Submitting a Pull Request
90+
91+
1. Fork the repo and create a branch from `main`.
92+
2. Make your changes. If adding a new reference file, also update the routing table in `CLAUDE.md` and `SKILL.md`.
93+
3. Test your changes by installing the skill locally and asking an agent a question that exercises the updated content:
94+
```
95+
npx skills add <path/to/powersync-ja/agent-skills>
96+
```
97+
4. Open a PR against `main` with a clear description of what changed and why.
98+
99+
### PR description checklist
100+
101+
- What file(s) changed?
102+
- What was wrong or missing?
103+
- Was any content removed, and if so, why?
104+
- If a new reference file was added, which entry point files were updated to route to it?
105+
106+
## Questions
107+
108+
Open an issue if you're unsure whether a change is in scope, or if you'd like feedback on an approach before writing a full PR.

LICENSE

Lines changed: 21 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,21 @@
1-
Creative Commons Legal Code
2-
3-
CC0 1.0 Universal
4-
5-
CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
6-
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
7-
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
8-
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
9-
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
10-
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
11-
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
12-
HEREUNDER.
13-
14-
Statement of Purpose
15-
16-
The laws of most jurisdictions throughout the world automatically confer
17-
exclusive Copyright and Related Rights (defined below) upon the creator
18-
and subsequent owner(s) (each and all, an "owner") of an original work of
19-
authorship and/or a database (each, a "Work").
20-
21-
Certain owners wish to permanently relinquish those rights to a Work for
22-
the purpose of contributing to a commons of creative, cultural and
23-
scientific works ("Commons") that the public can reliably and without fear
24-
of later claims of infringement build upon, modify, incorporate in other
25-
works, reuse and redistribute as freely as possible in any form whatsoever
26-
and for any purposes, including without limitation commercial purposes.
27-
These owners may contribute to the Commons to promote the ideal of a free
28-
culture and the further production of creative, cultural and scientific
29-
works, or to gain reputation or greater distribution for their Work in
30-
part through the use and efforts of others.
31-
32-
For these and/or other purposes and motivations, and without any
33-
expectation of additional consideration or compensation, the person
34-
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
35-
is an owner of Copyright and Related Rights in the Work, voluntarily
36-
elects to apply CC0 to the Work and publicly distribute the Work under its
37-
terms, with knowledge of his or her Copyright and Related Rights in the
38-
Work and the meaning and intended legal effect of CC0 on those rights.
39-
40-
1. Copyright and Related Rights. A Work made available under CC0 may be
41-
protected by copyright and related or neighboring rights ("Copyright and
42-
Related Rights"). Copyright and Related Rights include, but are not
43-
limited to, the following:
44-
45-
i. the right to reproduce, adapt, distribute, perform, display,
46-
communicate, and translate a Work;
47-
ii. moral rights retained by the original author(s) and/or performer(s);
48-
iii. publicity and privacy rights pertaining to a person's image or
49-
likeness depicted in a Work;
50-
iv. rights protecting against unfair competition in regards to a Work,
51-
subject to the limitations in paragraph 4(a), below;
52-
v. rights protecting the extraction, dissemination, use and reuse of data
53-
in a Work;
54-
vi. database rights (such as those arising under Directive 96/9/EC of the
55-
European Parliament and of the Council of 11 March 1996 on the legal
56-
protection of databases, and under any national implementation
57-
thereof, including any amended or successor version of such
58-
directive); and
59-
vii. other similar, equivalent or corresponding rights throughout the
60-
world based on applicable law or treaty, and any national
61-
implementations thereof.
62-
63-
2. Waiver. To the greatest extent permitted by, but not in contravention
64-
of, applicable law, Affirmer hereby overtly, fully, permanently,
65-
irrevocably and unconditionally waives, abandons, and surrenders all of
66-
Affirmer's Copyright and Related Rights and associated claims and causes
67-
of action, whether now known or unknown (including existing as well as
68-
future claims and causes of action), in the Work (i) in all territories
69-
worldwide, (ii) for the maximum duration provided by applicable law or
70-
treaty (including future time extensions), (iii) in any current or future
71-
medium and for any number of copies, and (iv) for any purpose whatsoever,
72-
including without limitation commercial, advertising or promotional
73-
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
74-
member of the public at large and to the detriment of Affirmer's heirs and
75-
successors, fully intending that such Waiver shall not be subject to
76-
revocation, rescission, cancellation, termination, or any other legal or
77-
equitable action to disrupt the quiet enjoyment of the Work by the public
78-
as contemplated by Affirmer's express Statement of Purpose.
79-
80-
3. Public License Fallback. Should any part of the Waiver for any reason
81-
be judged legally invalid or ineffective under applicable law, then the
82-
Waiver shall be preserved to the maximum extent permitted taking into
83-
account Affirmer's express Statement of Purpose. In addition, to the
84-
extent the Waiver is so judged Affirmer hereby grants to each affected
85-
person a royalty-free, non transferable, non sublicensable, non exclusive,
86-
irrevocable and unconditional license to exercise Affirmer's Copyright and
87-
Related Rights in the Work (i) in all territories worldwide, (ii) for the
88-
maximum duration provided by applicable law or treaty (including future
89-
time extensions), (iii) in any current or future medium and for any number
90-
of copies, and (iv) for any purpose whatsoever, including without
91-
limitation commercial, advertising or promotional purposes (the
92-
"License"). The License shall be deemed effective as of the date CC0 was
93-
applied by Affirmer to the Work. Should any part of the License for any
94-
reason be judged legally invalid or ineffective under applicable law, such
95-
partial invalidity or ineffectiveness shall not invalidate the remainder
96-
of the License, and in such case Affirmer hereby affirms that he or she
97-
will not (i) exercise any of his or her remaining Copyright and Related
98-
Rights in the Work or (ii) assert any associated claims and causes of
99-
action with respect to the Work, in either case contrary to Affirmer's
100-
express Statement of Purpose.
101-
102-
4. Limitations and Disclaimers.
103-
104-
a. No trademark or patent rights held by Affirmer are waived, abandoned,
105-
surrendered, licensed or otherwise affected by this document.
106-
b. Affirmer offers the Work as-is and makes no representations or
107-
warranties of any kind concerning the Work, express, implied,
108-
statutory or otherwise, including without limitation warranties of
109-
title, merchantability, fitness for a particular purpose, non
110-
infringement, or the absence of latent or other defects, accuracy, or
111-
the present or absence of errors, whether or not discoverable, all to
112-
the greatest extent permissible under applicable law.
113-
c. Affirmer disclaims responsibility for clearing rights of other persons
114-
that may apply to the Work or any use thereof, including without
115-
limitation any person's Copyright and Related Rights in the Work.
116-
Further, Affirmer disclaims responsibility for obtaining any necessary
117-
consents, permissions or other rights required for any use of the
118-
Work.
119-
d. Affirmer understands and acknowledges that Creative Commons is not a
120-
party to this document and has no duty or obligation with respect to
121-
this CC0 or use of the Work.
1+
MIT License
2+
3+
Copyright (c) 2025 PowerSync
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)