Agent skill · software engineering · jeremylongshore
notion-architecture-variants
Choose a Notion integration architecture from explicit consistency, latency, security, and recovery requirements. Use when comparing synchronous, queued, scheduled, or webhook-driven designs. Trigger with "design Notion architecture", "choose Notion sync pattern", or "review Notion topology".
Why this skill is useful
Adds executable integration code and architecture patterns for using Notion as a backend that aren't widely documented.
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 Architecture Decision Overview Choose a Notion integration architecture from explicit consistency, latency, security, and recovery requirements.. 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 Notion exposes versioned REST resources, paginated reads, connection webhooks, and mutable limits. Architecture must tolerate additive response fields, out-of-order signals, partial pagination, and changing quotas. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior. Authentication Map each component to a distinct connection or token boundary. Keep inbound webhook verification material, Notion access, queue administration, and destination credentials separated. Instructions 1. State the business operation, source of truth, consistency objective, recovery point, and recovery time. 2. Inventory reads, writes, webhook signals, scheduled reconciliation, files, and downstream processors. 3. Compare direct request, queued worker, scheduled batch, and webhook-plus-reconciliation variants. 4. Model pagination, retry, idempotency, backpressure, dead letters, and replay for each candidate. 5. Threat-model credentials, workspace content, tenant isolation, logs, and operator privileges. 6. Choose one variant with rejected alternatives, capacity assumptions, rollout gates, and 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/notion-architecture-variants--bc722c