Agent skill · software engineering · jeremylongshore
notion-reference-architecture
Define a production reference architecture for Notion access, operations, queues, reconciliation, and evidence. Use when standardizing multiple integration workloads. Trigger with "build Notion reference architecture", "standardize Notion services", or "review Notion platform design".
Why this skill is useful
Adds a complete production-ready architecture for Notion integrations, including executable code samples and design patterns not commonly found in public documentation.
What it needs
Requires @notionhq/client, node 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 Reference Architecture Overview Define a production reference architecture for Notion access, operations, queues, reconciliation, and evidence.. 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 A durable architecture separates transport, auth, tenant binding, object identity, schema mapping, operation logic, queues, idempotency, webhooks, reconciliation, telemetry, and evidence storage. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Centralize secret retrieval without centralizing plaintext. Bind every operation to connection, workspace, environment, capabilities, and approved content scope. Instructions 1. Define domain boundaries, sources of truth, tenant model, data classes, and service objectives. 2. Specify adapters for current pages, blocks, databases, data sources, search, files, and webhooks. 3. Place idempotency, checkpoints, backpressure, retry classification, and dead letters at explicit boundaries. 4. Add reconciliation as a first-class service independent of webhook delivery. 5. Define observability, evidence, privacy, retention, incident, and support interfaces. 6. Document deployment stages, compatibility policy, failure modes, and tested rollback. 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-reference-architecture--9b5263