Agent skill · software engineering · jeremylongshore
notion-known-pitfalls
Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes. Use when reviewing a release or investigating confusing failures. Trigger with "review Notion pitfalls", "find Notion integration mistakes", or "check Notion assumptions".
Why this skill is useful
Provides specific patterns and common pitfalls for Notion API integration that the AI wouldn't reliably generate on its own.
What it needs
Requires @notionhq/client, notion-client 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 Integration Pitfall Review Overview Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.. 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 Common failures arise from confusing databases with data sources, assuming capabilities equal content access, omitting pagination, pinning stale object shapes, treating webhooks as a ledger, or retrying writes without idempotency. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Check that the code distinguishes connection models, workspace binding, capabilities, shared content, and secret lifecycle. Instructions 1. Inventory all Notion clients, selected versions, tokens, object IDs, operations, and data flows. 2. Trace every database, data-source, page, block, file, search, and webhook assumption to first-party docs or a fixture. 3. Check pagination, size limits, unknown fields, error classes, Retry-After, and retry budgets. 4. Check idempotency, pre-state, read-back, compensation, and destructive-action approvals. 5. Check webhook signature, duplicate, ordering, aggregation, fetch-current, and reconciliation behavior. 6. Rank findings by exploitability, data impact, recurrence, and ease of correction. Tool Discipline Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/notion-known-pitfalls