@intentsolutionsio/notion-pack

Notion Skill Pack

30 production-ready skills for building Notion API integrations with @notionhq/client

Real API code. Real filter syntax. Real error handling. No placeholders.

What You Get

Every skill uses the official @notionhq/client SDK with actual Notion API patterns: database queries with typed filters, page creation with all property types, block content operations, rich text annotations, pagination, rate limit handling, webhook events, and OAuth flows.

Installation

/plugin install notion-pack@claude-code-plugins-plus

Skills (30)

Getting Started (S01-S12)

Skill	What It Does
notion-install-auth	Install @notionhq/client, create integration, configure OAuth
notion-hello-world	First API calls: search, query, create pages, append blocks
notion-local-dev-loop	Dev environment with hot reload, mocked tests, integration tests
notion-sdk-patterns	Singleton client, typed error handling, pagination helpers, property extractors
notion-core-workflow-a	Database queries with all filter types, page CRUD with typed properties
notion-core-workflow-b	Block content: append/read/update, rich text, comments, nested trees
notion-common-errors	Every Notion error code (401, 403, 404, 400, 429, 409, 502) with fixes
notion-debug-bundle	Diagnostic bundle: connectivity, SDK version, platform status, redacted logs
notion-rate-limits	3 req/s limit handling: SDK retry, p-queue throttling, batch processing
notion-security-basics	Token management, least-privilege capabilities, page-level access, rotation
notion-prod-checklist	Production readiness: auth, error handling, monitoring, data integrity, rollback
notion-upgrade-migration	SDK upgrades, API version migration, 2025-09-03 data source model

Integration (P13-P18)

Skill	What It Does
notion-ci-integration	GitHub Actions with mocked unit tests + gated live API integration tests
notion-deploy-integration	Deploy to Vercel, Fly.io, Cloud Run with secrets management
notion-webhooks-events	Webhook receiver: verification, event handling, idempotent processing
notion-performance-tuning	Caching, efficient pagination, parallel fetches, block batching
notion-cost-tuning	Reduce API volume: filters, timestamps, webhooks over polling
notion-reference-architecture	Layered project structure with extractors, services, error classification

Enterprise (F19-F24)

Skill	What It Does
notion-multi-env-setup	Per-environment integrations, secret management, environment guards
notion-observability	Prometheus metrics, structured logging, health checks, alert rules
notion-incident-runbook	Triage script, decision tree, mitigation by error type, postmortem template
notion-data-handling	PII detection in properties, redaction, GDPR export/deletion, retention
notion-enterprise-rbac	OAuth 2.0 multi-workspace, token storage, permission-aware API calls
notion-migration-deep-dive	CSV/JSON import, database export, cross-database sync, validation

Advanced (X25-X30)

Skill	What It Does
notion-advanced-troubleshooting	Debug logging, raw curl testing, request ID tracking, schema validation
notion-load-scale	Throughput benchmarks, k6 load tests, multi-token scaling, capacity planning
notion-reliability-patterns	Circuit breaker, cached fallback, idempotent creates, dead letter queue
notion-policy-guardrails	Secret scanning, ESLint rules, CI policy checks, TypeScript type guards
notion-architecture-variants	Direct/Service/Event-driven patterns with decision matrix
notion-known-pitfalls	10 common mistakes with correct patterns (wrong imports, missing pagination, etc.)

Key Notion Concepts Covered

• Property types: title, rich_text, number, select, multi_select, date, checkbox, url, email, phone_number, people, relation, formula, rollup
• Filter syntax: All property-specific filter conditions with compound and/or
• Block types: paragraph, headings, lists, to_do, code, callout, quote, toggle, divider
• Rich text: Annotations (bold, italic, code, color), links, mentions, equations
• Pagination: Cursor-based with start_cursor and has_more
• Rate limits: 3 req/s average, Retry-After header, SDK built-in retry
• Authentication: Internal tokens (ntn_*), OAuth 2.0 for public integrations
• Webhooks: Event types, verification handshake, idempotent processing

License

MIT