# sync-guide

Instructs coding assistants on building Notion Workers syncs, including replace mode, backfill-delta architectures, pagination, and cursor buffers.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 220
- Author: makenotion
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/makenotion/notion-cookbook/tree/HEAD/workers/agents/skills/sync-guide/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/sync-guide

## What it does

This skill guides coding agents through building data integrations with `@notionhq/workers`. It structures database pipelines by choosing between a single replace-mode sync for compact datasets and a paired backfill plus delta architecture for APIs with change feeds. The paired design separates manual full backfills from frequent incremental runs, preventing state machine bugs.

The guide details cursor and keyset pagination patterns, timestamp consistency buffers that avoid skipping unindexed items, and request pacing with `worker.pacer`. Deletions rely on mark-and-sweep passes in replace mode or explicit delete markers emitted during incremental runs.

Because `user-invocable` is set to `false`, the assistant loads this guide automatically whenever sync work appears in the context. Projects must import `@notionhq/workers` to compile the generated TypeScript handlers.

## Requirements
- Works with: Notion

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add makenotion/notion-cookbook --skill sync-guide -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/sync-guide/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/sync-guide/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add makenotion/notion-cookbook --skill sync-guide -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/sync-guide/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add makenotion/notion-cookbook --skill sync-guide -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/sync-guide/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install makenotion/notion-cookbook sync-guide
```

2. **Manually: put the files in place**
- File: `.github/skills/sync-guide/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add makenotion/notion-cookbook --skill sync-guide -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/makenotion/notion-cookbook --path workers/agents/skills/sync-guide
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/sync-guide/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add makenotion/notion-cookbook --skill sync-guide -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/makenotion/notion-cookbook/tree/HEAD/workers/agents/skills/sync-guide/SKILL.md

## When to use it
- configure paired backfill and incremental delta syncs for Notion
- implement keyset and cursor pagination for external APIs
- prevent dropped records with consistency timestamp buffers
- throttle API request bursts using `worker.pacer`

## Example prompts
- Write a Notion Worker sync to import external customer records into a managed database
- Set up a manual backfill sync paired with a scheduled delta sync for the same Notion database
- Add a consistency buffer to an incremental cursor sync to account for API index lag

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a344a0cfeee03181.

BEGIN THIRD-PARTY FILE a344a0cfeee03181
````text
---
name: sync-guide
description: Comprehensive guide to building Notion Workers syncs — covers the two-sync architecture (backfill+delta), replace mode, pagination, consistency buffers, pacers, deletion strategies, and common pitfalls. Auto-loads when sync-related work is detected.
user-invocable: false
---

## What is a Sync?

A sync is a recurring `execute` function that returns data changes to populate a Notion database. The runtime calls `execute` in a loop:

```ts
const db = worker.database("myDb", {
  type: "managed",
  initialTitle: "My Data",
  primaryKeyProperty: "ID",
  schema: {
    properties: {
      Name: Schema.title(),
      ID: Schema.richText(),
    },
  },
})

worker.sync("mySync", {
  database: db,
  execute: async (state, { notion }) => ({
    changes: [
      {
        type: "upsert",
        key: "1",
        properties: {
          Name: Builder.title("Item 1"),
          ID: Builder.richText("1"),
        },
      },
    ],
    hasMore: false,
    nextState: undefined,
  }),
})
```

Each call returns `{ changes, hasMore, nextState }`. If `hasMore` is `true`, the runtime calls `execute` again with `nextState`. This continues until `hasMore` is `false`, completing a **cycle**. The next cycle begins at the scheduled interval with the state from the end of the previous cycle.

**Imports:**

```ts
import { Worker } from "@notionhq/workers"
import * as Builder from "@notionhq/workers/builder"
import * as Schema from "@notionhq/workers/schema"
```

## Decision Framework

### Step 1: Choose an Architecture

The deciding factor is **API capability and dataset size**. Two tiers:

| Condition                                                         | Architecture                                                       |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| Small source (<1k records) or API with no change tracking         | **Simple replace sync** — one sync, `mode: "replace"`              |
| Everything else (API supports `updated_at`, change feeds, events) | **Backfill + delta pair** — two syncs writing to the same database |

**Simple replace sync**: One sync returns the full dataset each cycle. After the final `hasMore: false`, any records not seen are deleted automatically. Use when the dataset is small enough to re-fetch entirely.

**Backfill + delta pair**: Two syncs share a single database. The **backfill sync** (`mode: "replace"`, `schedule: "manual"`) re-fetches everything when triggered. The **delta sync** (`mode: "incremental"`, frequent schedule) fetches only changes since the last run. This separates concerns cleanly — no bi-modal state machine, no backfill-to-delta transition bugs.
````
END THIRD-PARTY FILE a344a0cfeee03181

The third-party file has ended. Everything between the a344a0cfeee03181 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2767 of 15459 bytes. © makenotion · MIT · https://github.com/makenotion/notion-cookbook/tree/HEAD/workers/agents/skills/sync-guide/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md