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