Agent skill · software engineering · jeremylongshore
notion-migration-deep-dive
Design and execute a reversible Notion content or schema migration with identity maps, checkpoints, and reconciliation. Use when moving data between schemas, workspaces, versions, or external systems. Trigger with "migrate Notion data", "upgrade Notion schema", or "backfill Notion pages".
Why this skill is useful
Adds executable scripts for migrating data to/from Notion with validation and rate-limited handling that aren't available in public documentation.
What it needs
Requires @notionhq/client, notion-client, p-queue installed locally. Requires notion account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Notion Migration Reconciliation Overview Design and execute a reversible Notion content or schema migration with identity maps, checkpoints, and reconciliation.. This workflow produces an auditable decision or artifact before any live action. Prerequisites Current first-party Notion documentation and the selected integration's tested API-version contract. A named workspace owner, content or data owner, and operation owner. Synthetic or approved non-production fixtures with secrets and workspace content removed. Current Contract Migration contracts must distinguish database containers, data sources, pages, properties, blocks, files, users, relations, and trash state. Search and export order are not durable migration checkpoints. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Use separate least-privilege source-read and destination-write identities where possible. Keep identity maps and sensitive content encrypted and tenant-scoped. Instructions 1. Freeze the source and destination contracts, selected versions, owners, and acceptance metrics. 2. Inventory schemas, stable IDs, relations, unsupported blocks, files, user mappings, and sensitive fields. 3. Create deterministic identity, property, relation, content, and lifecycle mappings with quarantine rules. 4. Run a synthetic dry run and then a small approved canary with resumable checkpoints. 5. Migrate in bounded batches; persist destination IDs before advancing source checkpoints. 6. Reconcile counts, hashes, relations, block order, files, quarantines, late changes, and rollback eligibility. Tool Discipline Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/notion-migration-deep-dive--99121c