Agent skill · software engineering · jeremylongshore
notion-sdk-patterns
Build a version-aware Notion SDK boundary with typed operations, pagination, error classification, and test seams. Use when writing or reviewing client code. Trigger with "design Notion SDK wrapper", "review Notion client code", or "update Notion SDK patterns".
Why this skill is useful
Provides specific patterns and examples for using the Notion SDK in TypeScript and Python that the AI wouldn't reliably generate on its own.
What it needs
Requires node, python 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 SDK Contract Patterns Overview Build a version-aware Notion SDK boundary with typed operations, pagination, error classification, and test seams.. 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 The official JavaScript SDK exposes current database, data-source, page, block, file, search, and auth operations. Pin and test an SDK/API combination; tolerate additive response fields and isolate vendor shapes. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Construct clients from a secret provider and tenant-bound connection profile. Never accept raw credentials through business-method arguments or return them in errors. Instructions 1. Define a narrow interface in domain terms rather than exporting the entire SDK client. 2. Pin the SDK and selected tested API version with an upgrade matrix. 3. Implement data-source identity resolution, complete pagination, property decoding, and unknown-field tolerance. 4. Classify structured errors and Retry-After before applying bounded retry. 5. Add idempotency and read-back at write boundaries, not inside generic transport retry. 6. Test adapters with fixtures plus a bounded non-production contract lane. 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-sdk-patterns--89048d