sync
/sync
Scaffold a new sync capability with guided setup — asks about data source, mode, pagination, and cursor design, then generates working code
- Author
- makenotion ↗
- Repository
- notion-cookbook ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Scaffold a new sync capability with guided setup — asks about data source, mode, pagination, and cursor design, then generates working code
Original author description
Scaffold a new sync capability with guided setup — asks about data source, mode, pagination, and cursor design, then generates working code
How it works
- Instructions
SKILL.md preview
---
name: sync
description: Scaffold a new sync capability with guided setup — asks about data source, mode, pagination, and cursor design, then generates working code
user-invocable: true
disable-model-invocation: true
allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "Agent"]
---
## Instructions
You are helping the user create a new sync capability for their Notion Worker. Walk through each step, asking questions and making recommendations. Generate working code at the end.
Before you begin, read these reference files to understand sync patterns:
- `.agents/skills/sync-guide/SKILL.md` — concepts, modes, patterns, common mistakes
- `.agents/skills/sync-guide/api-pagination-patterns.md` — real-world API strategies
- `.agents/skills/sync-guide/examples/` — working code templates
Also read the current `src/index.ts` to understand what already exists.
### Step 1: Understand the Data Source
Ask the user:
- What data are you syncing? (e.g., "Jira issues", "Stripe customers", "ServiceNow tickets")
If they name a well-known API, look up its pagination mechanism and change-tracking capabilities (does it have `updated_at`? an events endpoint? cursor-based pagination?).
### Step 2: Determine the Right Architecture
Based on what you know about the data source, recommend one of two architectures:
#### Simple replace sync
Use when: the source is small (<1k records) OR the API has no change tracking
(no `updated_at`, no event feed).
One sync, replace mode. Re-fetches everything each cycle. The runtime
auto-deletes records that disappear from the source. Simplest option.
#### Backfill + delta pair
Use when: the API supports change tracking (`updated_at`, events, changelog) —
this covers most enterprise APIs (Salesforce, Stripe, Linear, GitHub, HubSpot).
Two separate syncs writing to the **same database**:
- **Backfill sync** (replace mode, `schedule: "manual"`): Paginates the full
dataset. Triggered manually via CLI when a full re-import is needed. Replace
mode's mark-and-sweep automatically cleans up records deleted from the source.
- **Delta sync** (incremental mode, `schedule: "5m"` or similar): Fetches only
recently changed records. Runs on a timer for low-latency updates.
Advantages over a single bi-modal sync:
- No phase discrimination in state — each sync has simple, focused state
- No backfill-to-delta transition logic
- Backfill and delta run independently — re-backfill anytime without disrupting delta
- Easier to reason about and debug
**Change tracking drives the decision, not dataset size.** A Linear workspace
may only have a few thousand issues, but its API supports the queries needed
for delta sync, so backfill+delta is the right choice. Conversely, a website
listing local pickleball courts has no `updated_since` endpoint regardless of
how many records it has.
Recommend an architecture with a brief explanation. Let the user override if
they disagree.
### Step 3: Design the Schema
Based on the API's response shape, propose a schema. Look up what fields the
API returns and map the most useful ones to Schema types. Don't ask the user
to enumerate fields — propose a sensible default and let them adjust.
For example, if syncing Jira issues, propose:
```ts
const issuesDb = worker.database("issuesDb", {
type: "managed",
initialTitle: "Jira Issues",
primaryKeyProperty: "Issue Key",
schema: {
properties: {
"Issue Key": Schema.richText(), // primaryKeyProperty — the unique ID
Summary: Schema.title(), // the main display field
Status: Schema.select([
{ name: "To Do" },
{ name: "In Progress", color: "yellow" },
{ name: "Done", color: "green" },
]), // mapped from Jira statuses
Assignee: Schema.richText(), // or Schema.people() if email available
Updated: Schema.date(),
},
},
})
```
Guidelines:
- Declare the database with `worker.database()` and reference the handle in `worker.sync()`
- Every schema needs exactly one `Schema.title()` — pick the most descriptive field
- Use `Schema.richText()` for the primary key property (the unique ID)
- Treat property order as product design, not API order. Put the title first,
followed by the five properties that best help an end user recognize,
evaluate, or act on the record.
- Keep opaque IDs, sync keys, timestamps used only for cursors, and other
implementation metadata out of the first six properties. Include a user-facing
identifier such as an order number or issue key early only when users genuinely
rely on it.
- Use `Schema.url()`, `Schema.email()`, `Schema.date()`, `Schema.number()`,
`Schema.checkbox()`, `Schema.select()` where the data type fits
- Use `Schema.relation("otherDatabaseKey")` for relations to another managed database
- Start with 10-20 properties — be generous, include most useful fields from the API
- See the full type list in `.agents/skills/sync-guide/SKILL.md` under "Schema Reference"
Present the proposed schema to the user and ask if they want to add, remove,
or change any fields before generating code.
### Step 4: Design the State Machine
Research the API to determine its pagination and change-tracking mechanisms.
Do NOT ask the user about pagination details — figure it out from the API docs,
your knowledge of the API, or by looking up the API. The user shouldn't need
to know whether their API uses opaque cursors vs page numbers.
You need to determine:
1. **How the API paginates list results** (opaque cursor, page number, offset, keyset)
2. **Whether the API has change tracking** (updated_at field, events endpoint, changelog)
3. **Whether the API has deletion signals** (archived filter, audit log, delete events)
Then design the state accordingly:
**For simple replace syncs:** State is just within-cycle pagination.
- Opaque cursor: `{ cursor: string | null }`
- Page number: `{ page: number }`
**For backfill + delta pairs:** Each sync has its own simple state — no
bi-modal discriminated union needed.
- **Backfill state:** Just pagination cursor for walking the full dataset.
Depends on how the API paginates its list endpoint:
- Opaque cursor: `{ cursor: string | null }`
- Page number: `{ page: number }`
- Keyset: `{ cursorTimestamp: string | null; cursorId: string | null }`
- **Delta state:** Change-tracking cursor for fetching recent modifications.
Depends on how the API exposes changes:
- Opaque cursor (API sorted by updated_at): `{ cursor: string | null }`
- Timestamp keyset: `{ cursorTimestamp: string; cursorId: string }`
- Event ID: `{ eventCursor: string }`
**Consistency buffer (delta syncs only):** In incremental mode the cursor
never resets, so if you advance past a record that hasn't been indexed yet,
it's lost permanently. Apply a consistency buffer: never advance the cursor
closer than 10-15 seconds to "now". This is especially important for APIs
with eventual consistency (Stripe, Salesforce, etc.).
**Deletion handling:**
There are three cases to consider:
1. **API supports delta deletes** (e.g., Stripe events with `*.deleted` types,
APIs that return `deleted: true` in change feeds): Emit
`{ type: "delete", key }` in the delta sync. This is the cleanest approach.
2. **Deletes are rare or irrelevant** for the use case: No action needed.
Stale records remain in Notion but don't cause problems.
3. **Deletes matter but the API has no delete signal**: The backfill sync's
replace mode handles this automatically — its mark-and-sweep deletes any
records not seen during the full cycle. Trigger a backfill periodically
to clean up stale records.
If the API has no change tracking at all, go back and recommend a simple
replace sync instead.
Present your state design to the user as a brief summary (e.g., "This API uses
cursor-based pagination and has an `updated_at` field, so I'll use a
backfill+delta pair with opaque cursor for backfill and timestamp keyset for
delta"). Let them confirm or adjust before generating code.
### Step 5: Set Up Authentication
Before generating code, determine what auth the API needs and set it up so
you can test locally.
There are two patterns:
**Pattern A: Static API token/key**
For APIs where the user has a personal token or API key (e.g., Jira API token,
GitHub PAT, simple API keys).
Prefer a brokered credential when the token is only used in outbound request
headers to known domains. Follow `.agents/skills/auth-guide/SKILL.md` to declare
it with `worker.credential()`.
If the worker needs the plaintext token — for example, for signing or a request
body — tell the user which variables are needed and have them add the values
directly to `.env` themselves. Never ask them to send the values in chat:
```
JIRA_API_TOKEN=...
JIRA_EMAIL=user@example.com
```
If `.env` doesn't exist, create it. The `.env` file is automatically loaded
during local execution (`--local` flag).
**Pattern B: OAuth**
For APIs that require OAuth (e.g., Google, Salesforce, HubSpot). This has
two parts:
1. **Client credentials** — the OAuth app's client ID and secret. These go in `.env`:
```
MY_OAUTH_CLIENT_ID=...
MY_OAUTH_CLIENT_SECRET=...
```
2. **User token** — obtained through the OAuth flow _after_ deploying. This is
handled by the runtime automatically via `worker.oauth()` and `.accessToken()`.
For OAuth syncs, you'll add a `worker.oauth()` call in the generated code.
Always use `UserManagedOAuthConfiguration` (the shape with explicit endpoints and
client credentials) rather than the `{ provider: "..." }` shorthand, as
Notion-managed OAuth is in alpha and the user likely does not have access.
```ts
const myAuth = worker.oauth("myAuth", {
name: "my-provider",
authorizationEndpoint: "https://provider.example.com/oauth/authorize",
tokenEndpoint: "https://provider.example.com/oauth/token",
scope: "read write",
clientId: process.env.MY_OAUTH_CLIENT_ID ?? "",
clientSecret: process.env.MY_OAUTH_CLIENT_SECRET ?? "",
})
```
Then use `await myAuth.accessToken()` in the execute function instead of
reading a static token from `process.env`.
Note: the OAuth flow itself requires a deployed worker, but local execution works
after the first authorization completes and `ntn workers env pull` copies the
access token into `.env`. Before that bootstrap, `.accessToken()` fails because
the local token is missing. Proceed to Step 8 for the initial authorization.
### Step 6: Generate the Code
Write the sync into `src/index.ts`. Use the closest example from `.agents/skills/sync-guide/examples/` as a starting point:
- `replace-simple.ts` — static data, no API
- `replace-paginated.ts` — paginated replace mode (also used for backfill syncs)
- `incremental-basic.ts` — delta sync with opaque cursor
- `incremental-bimodal.ts` — full backfill + delta pair example
- `incremental-events.ts` — delta sync with event feed
Include in the generated code:
- Proper imports (`Worker`, `Builder`, `Schema`)
- Database declaration via `worker.database()` with schema and `primaryKeyProperty`
- A pacer for the upstream API via `worker.pacer()` — and `await pacer.wait()` before every API request
- The state type(s) — simple types, one per sync (no discriminated unions needed)
- The `worker.sync()` call(s) referencing the database handle
- For backfill+delta: two syncs targeting the same database, backfill with `schedule: "manual"`, delta with a timed schedule
- A consistency buffer for delta syncs (if the API is eventually consistent)
- Inline comments explaining _why_ each design choice was made
- API calls using `fetch` with auth from a brokered credential or `process.env`
**Code generation checklist:**
- [ ] Database declared with `worker.database()` and referenced by handle
- [ ] Pacer declared with `worker.pacer()` for the upstream API
- [ ] `await pacer.wait()` called before every `fetch` to the upstream API
- [ ] State types are simple (no bi-modal discriminated unions)
- [ ] Backfill sync uses `mode: "replace"` and `schedule: "manual"` (if applicable)
- [ ] Delta sync uses `mode: "incremental"` with a timed schedule (if applicable)
- [ ] Consistency buffer applied to delta cursor advancement (if applicable)
- [ ] Deletion handling matches one of the three cases from Step 4
### Step 7: Test Locally
Test the sync before deploying. This catches bugs early without a deploy cycle.
**For syncs using static API tokens (Pattern A):**
Brokered credentials must be tested after deploy in Step 8. For tokens read
from `process.env`, test locally:
1. Run `npm run check` to verify TypeScript types compile. Fix any errors.
2. Run `ntn workers exec <key> --local` to execute the sync locally.
This runs the execute function on your machine with `.env` loaded.
- Check: does it return data? Are properties populated correctly?
- Check: does `hasMore` look right? Does the cursor advance?
3. If it returns `hasMore: true`, test the next page:
`ntn workers exec <key> --local -d '<nextState from previous output>'`
4. If there are errors (auth failures, wrong field mappings, crashes):
fix the code and re-run — no deploy needed, iteration is fast.
5. For backfill+delta pairs, test each sync independently:
- Test the backfill sync: `ntn workers exec <backfillKey> --local`
- Test the delta sync: `ntn workers exec <deltaKey> --local`
- Verify they both return well-formed data with the correct properties.
6. Write a test file (`test.ts`) that exercises the sync. Import the worker
directly and call its `.run()` method.
If the user has API credentials in `.env`, write a test that hits the real
API — this is the most valuable test because it validates actual field
mappings, pagination behavior, and auth against the real service. If
credentials aren't available, stub the HTTP calls instead.
**Integration test (preferred when credentials are available):**
```ts
import "dotenv/config" // load .env
import worker from "./src/index.ts"
import assert from "node:assert"
async function test() {
// First page (backfill start, no prior state)
const page1 = await worker.run("mySync", undefined, {
concreteOutput: true,
})
console.log(
`Page 1: ${page1.changes.length} records, hasMore: ${page1.hasMore}`
)
assert(page1.changes.length > 0, "Should return records")
// Verify fields are populated
const first = page1.changes[0]
assert(first.key, "Record should have a key")
console.log("Sample record:", JSON.stringify(first, null, 2))
// Test pagination
if (page1.hasMore) {
const page2 = await worker.run("mySync", page1.nextState, {
concreteOutput: true,
})
console.log(
`Page 2: ${page2.changes.length} records, hasMore: ${page2.hasMore}`
)
assert(page2.changes.length > 0, "Second page should return records")
}
console.log("All tests passed!")
}
test().catch((err) => {
console.error(err)
process.exit(1)
})
```
Run with `npx tsx test.ts`. Adapt to the specific sync: use the actual
capability key, add assertions for specific field values, verify both
backfill and delta syncs for backfill+delta pairs, etc.
**For syncs using OAuth (Pattern B):**
Before the first authorization, local execution won't work because
`.accessToken()` requires a token from a completed OAuth flow. After deploying,
completing the flow, and running `ntn workers env pull`, local execution works.
You can always run `npm run check` for type validation.
### Step 8: Deploy and Validate with Preview
Once local testing passes (or immediately for OAuth syncs), deploy and test remotely.
If secrets need to be available at deploy time (e.g., OAuth `clientSecret` read
from `process.env` during capability registration), create the worker and push
secrets first:
1. `ntn workers create --name <name>` — create the worker without deploying
2. `ntn workers env push` — push `.env` secrets to remote
3. `ntn workers deploy` — now deploy with secrets available
Otherwise, the simpler flow:
1. `ntn workers deploy` — build and publish
2. `ntn workers env push` — push `.env` secrets to remote
3. Then, if the sync uses OAuth, complete the OAuth flow before previewing.
**Important:** `env push` must happen before `oauth start` — the deployed worker needs the client secret to exchange the authorization code for tokens.
- `ntn workers oauth show-redirect-url` — get the redirect URL
- Tell the user to configure this URL in their OAuth provider's app settings
- `ntn workers oauth start <oauthKey>` — opens browser to complete the OAuth flow
4. `ntn workers sync trigger <syncKey> --preview` — execute remotely without writing to Notion
- Inspect the output: record count, property values, hasMore status
- If `hasMore: true`, continue: `ntn workers sync trigger <syncKey> --preview --context '<nextState>'`
5. If the preview shows issues, fix the code and redeploy (go back to step 1)
For backfill+delta pairs, preview both syncs:
- `ntn workers sync trigger <backfillKey> --preview`
- `ntn workers sync trigger <deltaKey> --preview`
### Step 9: Go Live
When the preview looks good:
1. `ntn workers sync trigger <key>` — trigger a real sync
2. `ntn workers sync status` — check that the sync is running and progressing
3. `ntn workers runs list` then `ntn workers runs logs <runId>` — check for errors
4. Run `ntn workers sync status` again to confirm progress (record count increasing, no errors)
For backfill+delta pairs, initialize the delta cursor before loading all data,
so changes made during the backfill are not skipped:
1. `ntn workers sync trigger <deltaKey>` — initialize the delta cursor
2. `ntn workers sync trigger <backfillKey>` — start the full dataset load
3. Monitor with `ntn workers sync status` until the backfill completes
4. The delta sync will continue automatically on its configured schedule
Tell the user: initialize the delta cursor before starting the backfill. The
backfill may take a while depending on dataset size. They should periodically
run `ntn workers sync status` to monitor progress until the initial backfill
completes. After that, the delta sync runs automatically on its configured
schedule. To re-backfill later:
`ntn workers sync state reset <backfillKey> && ntn workers sync trigger <backfillKey>`
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · makenotion/notion-cookbook | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| wookiya1364/scv-claude-code | 100 | MIT |
| biliboss/skills | 100 | MIT |
| olehsov/gcp-certification-coach | 100 | MIT |
| lucastamoios/skills | 100 | MIT |
| enzo-thuilliez/my-starter-kit | 100 | MIT |
Identical content appears in 34 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 4fe0f4b88278 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100pagination-and-sync-engineer
Designs correct cursor pagination and incremental delta sync against a mutating dataset - cursor contracts, updated_at watermarks, delete propagation, checkpointing, and idempotent reprocessing. Use when someone says "my sync is skipping rows", "should I use cursor or offset… - 95sync-profiles
Use when the user wants to list, create, switch, delete, compare, or inspect config sync profiles. - 91add-tool
Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server. - 96s04-01-web-scaffold
按架构选型生成前后端工程骨架、目录规范与构建配置。当用户要求'搭脚手架/初始化工程/建项目骨架'时使用。产出可运行的空工程。 - 100pagination-helper
Configure with pagination helper operations. Auto-activating skill for API Development. Triggers on: pagination helper, pagination helper Part of the API Development skill category. Use when working with pagination helper functionality. Trigger with phrases like "pagination… - 100cursor-privacy-settings
Configure Cursor privacy and data handling settings. Triggers on "cursor privacy", "cursor data", "cursor security", "privacy mode", "cursor telemetry". Use when working with cursor privacy settings functionality. Trigger with phrases like "cursor privacy settings", "cursor settings", "cursor".