Claude Code skill pack for Notion (30 skills)

30 Skills

MIT License

Installation

Open Claude Code and run this command:

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

Use --global to install for all projects, or --project for current project only.

What It Does

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

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

Skills (32)

notion-advanced-troubleshooting View full skill →

Use when standard Notion troubleshooting fails or you are chasing intermittent API errors — deep debugging for response inspection, permission chain tracing, property type mismatches, pagination edge cases, and block nesting limits.

ReadGrepBash(curl:*)Bash(node:*)

Notion Advanced Troubleshooting

Overview

Deep debugging techniques for Notion API issues that resist standard fixes —

API response inspection with request IDs, permission chain tracing, property

type mismatch detection, pagination edge cases, and block nesting limit

violations (max depth of 3 levels via API). Full runnable TypeScript and Python

for every step lives in references/implementation.md.

Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Python: notion-client installed (pip install notion-client)
curl available for raw API testing
NOTIONTOKEN environment variable set (internal integration token starting with ntn)
Pages/databases shared with your integration via Notion UI

Authentication

All calls authenticate with a single internal integration token in the

NOTION_TOKEN environment variable — the SDK reads it via `auth:

process.env.NOTION_TOKEN, and raw curl` sends it as

Authorization: Bearer $NOTION_TOKEN plus the Notion-Version: 2022-06-28

header. Never hardcode the token; keep it in the environment. Confirm the token

is a bot token with notion.users.me() — if the returned type is not bot,

the token is wrong. A 401 unauthorized means a bad/expired token; a `404

objectnotfound` on a valid page means the token is fine but the resource

was never shared with the integration (see Step 2).

Instructions

Work the steps in order — each narrows where the failure lives. Read the

full walkthrough for the complete function

bodies; the skeletons below show the entry point of each.

Step 1: API Response Inspection with Request ID Tracking

Every Notion API response carries an x-request-id header. Enable

LogLevel.DEBUG and wrap calls so every request logs its ID and timing —

capture that ID for support tickets. Use Grep over the debug log to find a

specific request's ID after the fact.


const notion = new Client({ auth: process.env.NOTION_TOKEN, logLevel: LogLevel.DEBUG });

async function tracedCall<T>(label: string, fn: () => Promise<T>) {
  const start = Date.now();
  try {
    const result = await fn();
    console.log(`[${label}] OK ${Date.now() - start}ms`);
    return result;
  } catch (error) {
    if (isNotionClientError(error)) console.error(`[${label}] FAILED`, error.code, error.body);
    throw error;
  }
}

To isolate SDK-vs-transport bugs, replay the same call with ra

notion-architecture-variants View full skill →

Use when you are choosing or scaffolding how an app talks to Notion via the API — deciding between a headless CMS (blog/content site), a task tracker (project management), a knowledge base (wiki), a form-submission handler, or a data-pipeline source, and wiring the database schema plus integration code.

ReadWriteEditBash(node:*)

Notion Architecture Variants

Overview

Five validated architecture patterns for using Notion as a backend via the API, each with database schema design, integration code, and deployment tradeoffs. The full copy-ready code for every variant lives in references/implementation.md; this page gives the decision framework, the shared skeleton, and one worked example so you can pick the right pattern and drill into depth on demand.

The five variants:

Variant	Use case	Core operation
Headless CMS	Blog / content site	Query `Status = Published`, render blocks to HTML
Task Tracker	Project management	Group by status for a board, `pages.update` on move
Knowledge Base	Wiki / internal docs	Workspace `search` filtered to the wiki database
Form Handler	Contact / lead capture	One `pages.create` per submission
Data Pipeline	Analytics / ETL source	Paginate on a `lasteditedtime` watermark

Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set
Notion databases created and shared with your integration

Authentication

All variants authenticate the same way: an internal integration token in the

NOTION_TOKEN environment variable, passed as auth when constructing the

client (new Client({ auth: process.env.NOTION_TOKEN }) / Client(auth=...)).

Create the integration at notion.so/my-integrations, then **share each database

with the integration** from its Notion page — an unshared database returns

objectnotfound even with a valid token. Never hard-code the token; read it

from the environment.

Instructions

Pick the variant that matches your workload using the decision helper in

references/examples.md — content authoring vs.

real-time status vs. high read volume each point to a different pattern.

Model the database schema in Notion for that variant (property names and

types are documented inline with each variant's code). Share the database

with your integration.

Read any existing integration module, then Write the client setup:

construct one Client with auth: process.env.NOTION_TOKEN

notion-ci-integration View full skill →

'Integrate the Notion API into CI/CD pipelines for automated documentation.

ReadWriteEditBash(gh:*)Bash(npm:*)Bash(npx:*)Bash(python3:*)

Notion CI Integration

Overview

Integrate the Notion API into CI/CD pipelines for automated documentation sync, deploy tracking, and configuration reads. GitHub Actions workflows push release notes to Notion pages, upsert deploy entries in databases, create incident pages, and read feature flags — all with rate-limit handling, and each concern in its own reference file for copy-ready code.

Prerequisites

GitHub repository with Actions enabled
Notion internal integration token (create at https://www.notion.so/my-integrations)
Target Notion pages/databases shared with the integration (click "..." > "Connections" > add the integration)
NOTION_TOKEN stored as a GitHub Actions secret
Node.js 18+ or Python 3.9+ in the CI environment

Authentication

Every request authenticates with an internal integration token passed as a bearer

credential. The Notion SDKs read it from the NOTION_TOKEN environment variable

(new Client({ auth: process.env.NOTION_TOKEN }) in Node, Client(auth=token) in

Python). Store it as a repository secret and inject it per job — never hardcode it

(gh secret set NOTION_TOKEN). A token only reaches pages and databases explicitly

shared with the integration (page menu > "Connections" > add integration); an unshared

target returns 404 Object not found, not 401 — see Error Handling.

Instructions

The integration is three composable pieces — read each summary for its shape, then open the linked reference for complete, copy-ready code.

Step 1: Workflow for documentation sync

Add a workflow that reacts to release: published and pushes to main. It runs three

jobs — create a release-notes page, sync the CHANGELOG.md page, and update the deploy

tracker — each injecting NOTION_TOKEN and the relevant database ID as env:


# .github/workflows/notion-docs-sync.yml
on:
  release: { types: [published] }
env:
  NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
jobs:
  sync-release-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4      # + npm ci (see reference)
      - run: node scripts/notion-release-sync.js
        env:
          NOTION_RELEASES_DB: ${{ secrets.NOTION_RELEASES_DB }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}

See full workflow YAML for all three jobs, the

changelog push trigger, and the needs:-gated deploy-status job.

Step 2: CI scripts for Notion operations

Back the workflow with small scripts. The release-notes script creates a database page

and appe

notion-common-errors View full skill →

'Diagnose and fix Notion API errors by HTTP status code and error code.

ReadGrepBash(curl:*)

Notion Common Errors

Overview

Quick reference for all Notion API error codes with exact HTTP statuses, error bodies, and fixes. The API returns errors as JSON with three fields:


{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "Title is not a property that exists."
}

All requests require Authorization: Bearer $NOTION_TOKEN and Notion-Version: 2022-06-28 headers (2022-06-28 is the current stable API version — the header is required on every call).

This SKILL.md gives you the triage table and workflow. Two references carry the depth:

references/error-codes.md — the full per-status playbook (401, 403, 404, 400, 429, 409, 500, 502/503) with error bodies, causes, and code fixes.
references/examples.md — the full SDK error handler, the curl diagnostic script, and the non-HTTP client-side gotchas (rich text arrays, pagination, timeouts).

Prerequisites

@notionhq/client installed (npm install @notionhq/client)
NOTIONTOKEN environment variable set (internal integration token starting with ntn or secret_)
Target pages/databases shared with the integration via the Connections menu

Instructions

Step 1: Identify the Error

Read the JSON error body returned by the failed request.
Note its HTTP status and machine-readable code fields — those two values route you to the exact fix.
If you only have logs, Grep your application logs for the code field to recover the values.

Step 2: Match Error Code and Apply Fix

Use the Error Handling table below to see whether the error is retryable and the recommended action. For the exact error body, root cause, and copy-paste fix, open the matching section in references/error-codes.md. The four you will hit most:

404 objectnotfound — the most common error. The page/database exists but is not shared with your integration. Fix via the ... → Connections menu; parent pages must be shared too.
401 unauthorized — token missing, malformed, expired, or revoked. Verify with curl .../v1/users/me; regenerate at notion.so/my-integrations.
400 validation_error — the broadest category, usually a wrong property name/type or a filter-type mismatch (e.g. status:

notion-content-management View full skill →

'Create, update, archive, and compose Notion pages and block content.

ReadWriteEdit

Notion Content Management

Overview

Complete guide to creating, updating, archiving, and composing Notion pages and block content using the @notionhq/client SDK. Covers page lifecycle, all common block types, rich text formatting, and bulk content operations. The core workflow lives here at a high level; deep code walkthroughs are extracted into references/ so this file stays scannable.

Prerequisites

Completed notion-install-auth setup
NOTION_TOKEN environment variable set
Target database or page shared with the integration (via Connections menu)
@notionhq/client v2+ installed (TypeScript) or notion-client (Python)

Instructions

Step 1: Create, Update, and Archive Pages

Create a page in a database with typed properties (title, select, multi_select, date, people, number, checkbox, url), an optional icon/cover, and initial children block content. Update properties with pages.update (set a property to null to clear it). Archive is a soft-delete via archived: true, and restore flips it back to false.

Minimal skeleton:


import { Client } from '@notionhq/client';
const notion = new Client({ auth: process.env.NOTION_TOKEN });

const page = await notion.pages.create({
  parent: { database_id: databaseId },
  properties: { Name: { title: [{ text: { content: 'Q1 Retro' } }] } },
});
await notion.pages.update({ page_id: page.id, properties: { Status: { select: { name: 'Done' } } } });
await notion.pages.update({ page_id: page.id, archived: true });  // archive

Full typed-property create, update-with-clear, and archive/restore functions: page lifecycle walkthrough.

Step 2: Compose Content with Block Types

Append blocks to an existing page with blocks.children.append. Each block type has its own payload shape — headings, paragraphs (with rich text annotations), bulleted/numbered lists, to-dos, toggles, code blocks, callouts, quotes, dividers, images, and tables are all supported. The full catalog with the exact shape for every block type is in the block type catalog.

The minimal pattern:


await notion.blocks.children.append({
  block_id: pageId,
  children: [
    { heading_2: { rich_text: [{ text: { content: 'Notes' } }] } },
    {
      paragraph: {
        rich_text: [
          { text: { content: 'Plain and ' } },
          { text: { content: 'bold' }, annotations: { bold: true } },
        ],
      },
    },
    { to_do:


                
                  
                  notion-core-workflow-a
                  View full skill →
                
                
                  'Query, filter, and manage Notion databases and pages.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Notion Core Workflow A — Databases & Pages
Overview
Primary workflow for Notion integrations: querying databases with filters/sorts, creating pages with typed properties, updating page properties, and retrieving page content.
Prerequisites

Completed notion-install-auth setup
A Notion database shared with your integration
Understanding of your database's property schema

Authentication
Every call below uses a Client authenticated with an integration token
(process.env.NOTION_TOKEN). Token creation, secret storage, and sharing a
database with the integration are covered end-to-end in the notion-install-auth
skill — complete it first. Never hardcode the token; read it from the environment.
Instructions
The workflow is six steps. Steps 1–2 (schema + filtered query) are the skeleton
you almost always start with, shown here in full. Steps 3–6 (filter syntax by
type, page creation, updates/archive, pagination) live in
the full walkthrough so this file stays scannable.
Step 1: Retrieve Database Schema
Always inspect the schema first — property names and types drive every filter
and write. databases.retrieve returns db.properties keyed by property name.

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function getDatabaseSchema(databaseId: string) {
  const db = await notion.databases.retrieve({ database_id: databaseId });
  for (const [name, prop] of Object.entries(db.properties)) {
    console.log(`${name}: ${prop.type}`);
    if (prop.type === 'select') {
      console.log('  Options:', prop.select.options.map(o => o.name));
    }
  }
  return db.properties;
}

Step 2: Query with Filters
Notion filters use a nested structure keyed by property type, and combine with
and / or. sorts and page_size (max 100) tune the result set.

async function queryWithFilters(databaseId: string) {
  const response = await notion.databases.query({
    database_id: databaseId,
    filter: {
      and: [
        { property: 'Status', select: { equals: 'In Progress' } },
        { property: 'Priority', select: { does_not_equal: 'Low' } },
      ],
    },
    sorts: [{ property: 'Priority', direction: 'ascending' }],
    page_size: 50,
  });
  return response.results;
}

Steps 3–6: Filter syntax, create, update, paginate
See the full walkthrough for copy-paste code:

Step 3 — Filter syntax by property type.
                

              

                
                  
                  notion-core-workflow-b
                  View full skill →
                
                
                  Work with Notion blocks, rich text, comments, and page content.
                  
                      ReadWriteBash(npm:*)
                    
                
                
                  Notion Core Workflow B — Blocks, Content & Comments
Overview
Secondary workflow for content operations: reading block trees, appending content, building rich text with annotations, and managing comments. SKILL.md keeps the flow at a high level; every full implementation lives in references/implementation.md.
Prerequisites

Completed notion-install-auth setup
A Notion page shared with your integration
Familiarity with notion-core-workflow-a (databases/pages)

Authentication
All calls use the @notionhq/client SDK authenticated with an integration token read from process.env.NOTIONTOKEN. The token is provisioned by the notion-install-auth skill (internal integration secret) — do not hard-code it. The page or block being edited must be explicitly shared with that integration, or calls return objectnot_found.
Instructions
The workflow has six steps. The client is created once and reused:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });


Retrieve block children — page through notion.blocks.children.list with a startcursor loop (100 blocks/page) until hasmore is false.
Read blocks recursively — walk each block, and when haschildren is true recurse to build a nested tree; blockToText flattens a block's richtext to a plain string.
Append content blocks — one notion.blocks.children.append call adds headings, formatted paragraphs, bulleted/numbered lists, to-dos, code, callouts, quotes, dividers, and toggles.
Rich text annotations — each rich-text span carries annotations (bold, italic, strikethrough, underline, code, color); spans can be plain text, links, user/page/date mentions, or LaTeX equations.
Update and delete blocks — notion.blocks.update replaces a block's content; notion.blocks.delete archives it.
Work with comments — notion.comments.create adds page or discussion-thread comments; notion.comments.list reads them back.

Each step's complete, copy-paste code is in references/implementation.md.
Output

Page content blocks retrieved (flat or recursive tree)
Rich content appended with formatting, lists, code, callouts
Blocks updated and deleted
Comments created and listed

Error Handling

                
              

                
                  
                  notion-cost-tuning
                  View full skill →
                
                
                  'Optimize Notion API usage to minimize rate-limit pressure, reduce engineering.
                  
                      ReadWriteEditBash(npm:*)GlobGrep
                    
                
                
                  Notion Cost Tuning
Overview
The Notion API is free with every workspace plan — there is no per-call pricing. The real "cost" is the 3 requests/second rate limit (per integration token) plus the engineering time wasted on inefficient patterns. Apply the six strategies below to reduce request volume by 80-95%.
Notion workspace pricing (for context — API access is included at every tier):

Plan
Price
API Access
Rate Limit


Free
$0
Full API
3 req/sec


Plus
$12/user/mo
Full API
3 req/sec


Business
$28/user/mo
Full API
3 req/sec


Enterprise
Custom
Full API
3 req/sec


The rate limit is identical across all plans. Optimization is about staying within 3 req/sec, not reducing a bill.
Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Integration token from notion.so/my-integrations
Token shared with target pages/databases via the Connections menu in Notion
For queue patterns: p-queue v8+ (npm install p-queue)
For caching: node-cache or lru-cache (npm install lru-cache)

Authentication
Every technique here uses the same auth as any Notion integration: a single bearer token passed to the client constructor. Store it in an environment variable (NOTION_TOKEN) — never hardcode it — and share it with each target page/database through the Connections menu. One token = one 3 req/sec budget; provision a separate integration token per service when you need independent budgets.

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Instructions
Work the three steps in order. Each links to the full, copy-paste-ready code in references/implementation.md; the essentials are inlined below so you can follow the flow from here.
Step 1: Audit current request volume
Measure before optimizing. Wrap every Notion call in a tracker that records method, endpoint, timestamp, and duration, then print a per-minute report to find the operations eating > 50% of your budget (usually polling loops, redundant retrieves, and full-table scans).

async function tracked<T>(method: string, fn: () => Promise<T>): Promise<T> {
  const start = Date.now();
  try {
    return await fn();
  } finally {
    requestLog.push({ method, timestamp: start, durationMs: Date.

                

              

                
                  
                  notion-data-handling
                  View full skill →
                
                
                  Implement data handling, PII protection, and GDPR/CCPA compliance for Notion integrations.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Data Handling
Overview
Handle sensitive data correctly when integrating with Notion: detect PII in page
properties and text content, redact sensitive fields before logging or exporting,
minimize data exposure with filter_properties, and implement GDPR/CCPA compliance
patterns — right-of-access exports, right-of-deletion (archive or field clearing), and
retention-based archival, all with audit logging.
The full, copy-ready TypeScript and Python implementations live in references/ so this
file stays a navigable map. Read top-to-bottom for the workflow; drill into a reference
file when you need the complete code for a step.
Prerequisites

@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Understanding of which Notion databases contain personal data
Audit logging infrastructure (structured logs, SIEM, or Notion audit database)
Legal guidance on applicable regulations (GDPR, CCPA, HIPAA, etc.)

Authentication
All examples authenticate with an internal integration token read from the environment —
never hardcode it:

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Create the token at notion.so/my-integrations and
share each target database with the integration. Deletion and retention flows additionally
require the integration to hold Update capability, or pages.update returns 403.
Instructions
Work through three stages. Each links to a reference file with the complete implementation.
Step 1 — Detect PII
Notion pages carry PII in dedicated email/phone_number/people properties and
embedded in free-text rich_text/title values. Scan both: check known-sensitive
property types directly, and run regex matchers (email, phone, SSN, credit card, IP) over
text. Loop the whole database through pagination until has_more is false. Skeleton:

function scanPageForPII(page: PageObjectResponse): PIIFinding[] {
  // check email / phone_number / people property types,
  // then run PII_PATTERNS regexes over rich_text + title text
}

Full TS + Python scanners: pii-detection.md.
Step 2 — Redact and minimize
Never log or export raw page objects. Pass every page through an allowlist-shaped redactor
that masks sensitive property types and named fields while letting vetted scalar types pass
through. Then cut exposure at the source with <
                
              

                
                  
                  notion-debug-bundle
                  View full skill →
                
                
                  'Collect Notion API diagnostic info for troubleshooting and support tickets.
                  
                      ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Bash(npm:*)Bash(node:*)
                    
                
                
                  Notion Debug Bundle
Overview
Collect diagnostic information for Notion API issues: SDK version, token validity, database access, page sharing status, rate limits, and platform health. The Notion API requires integrations to be explicitly invited to each page or database — most "not found" errors are sharing problems, not code bugs.
Prerequisites

@notionhq/client installed (npm ls @notionhq/client to verify)
NOTIONTOKEN environment variable set (internal integration token, starts with ntn)
curl and jq available for shell-based diagnostics

Instructions
Step 1: Quick Connectivity and Auth Check

#!/bin/bash
echo "=== Notion Debug Check ==="
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# 1. SDK version
echo -e "\n--- SDK Version ---"
npm ls @notionhq/client 2>/dev/null || echo "SDK not found — run: npm install @notionhq/client"

# 2. Runtime and token status
echo -e "\n--- Runtime ---"
node --version 2>/dev/null || echo "Node.js not found"
echo "NOTION_TOKEN: ${NOTION_TOKEN:+SET (${#NOTION_TOKEN} chars)}"
TOKEN_PREFIX="${NOTION_TOKEN:0:4}"
if [ -n "$NOTION_TOKEN" ] && [ "$TOKEN_PREFIX" != "ntn_" ]; then
  echo "WARNING: Token does not start with 'ntn_' — may be using legacy format"
fi

# 3. API connectivity — /v1/users/me as health check
# Notion-Version 2022-06-28 is the current stable REST API version.
echo -e "\n--- API Connectivity ---"
RESPONSE=$(curl -s -w "\n%{http_code}\n%{time_total}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" 2>&1)

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
LATENCY=$(echo "$RESPONSE" | tail -2 | head -1)
BODY=$(echo "$RESPONSE" | head -n -2)

echo "HTTP Status: $HTTP_CODE"
echo "Latency: ${LATENCY}s"

if [ "$HTTP_CODE" = "200" ]; then
  echo "Bot Name: $(echo "$BODY" | jq -r '.name // "unknown"')"
  echo "Bot Type: $(echo "$BODY" | jq -r '.type // "unknown"')"
else
  echo "Error Code: $(echo "$BODY" | jq -r '.code // "unknown"')"
  echo "Message: $(echo "$BODY" | jq -r '.message // "unknown"')"
fi

# 4. Notion platform status
echo -e "\n--- Notion Platform Status ---"
curl -s https://status.notion.so/api/v2/status.json \
  | jq -r '.status.description // "Could not reach status page"' 2>/dev/null \
  || echo "Could not reach status.notion.so"

# 5. Rate limit baseline (3 req/sec across all endpoints

                

              

                
                  
                  notion-deploy-integration
                  View full skill →
                
                
                  Deploy Node.
                  
                      ReadWriteEditBash(npx:*)Bash(vercel:*)Bash(railway:*)Bash(fly:*)
                    
                
                
                  Deploy Notion-Integrated Applications
Overview
Ship Node.js apps that talk to the Notion API to Vercel, Railway, or Fly.io. This skill covers environment variable management, the Notion client singleton pattern for serverless, rate limit handling at 3 req/sec, health check endpoints that verify Notion connectivity, and caching strategies to reduce API calls.
Deep code lives in references/ so this file stays a lean walkthrough. Read a reference when a step needs the full module, then Write or Edit the code into your project's src/.
Prerequisites

Node.js >= 18 project with @notionhq/client installed (npm i @notionhq/client)
Working Notion integration tested locally with a valid NOTIONTOKEN (starts with ntn)
Platform CLI installed for your target: vercel, railway, or fly
Database or page IDs your integration needs access to

Authentication
Every request authenticates with an internal integration token (NOTIONTOKEN, prefix ntn), created at notion.so/my-integrations and passed as auth to the client. In production the token is stored as an encrypted platform secret and injected at runtime — never committed to source. Store it with vercel env add NOTIONTOKEN production, railway variables set NOTIONTOKEN=..., or fly secrets set NOTION_TOKEN=.... Each database or page must also be explicitly shared with the integration in the Notion UI, or queries return ObjectNotFound.
Instructions
Step 1 — Prepare the application for production
Build a production entry point with four modules: a Notion client singleton, a rate limiter, a response cache, and a health check. The singleton is the essential piece — serverless containers recycle unpredictably, so a module-level client reuses connections across warm invocations instead of paying cold-start and rate-limit cost per request:

// src/notion-client.ts — singleton for serverless environments
import { Client, LogLevel } from '@notionhq/client';

let client: Client | null = null;

export function getNotionClient(): Client {
  if (!client) {
    if (!process.env.NOTION_TOKEN) {
      throw new Error('NOTION_TOKEN environment variable is not set');
    }
    client = new Client({
      auth: process.env.NOTION_TOKEN,
      logLevel: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
      timeoutMs: 30_000,
    });
  }
  return client;
}

The rate limiter (token bucket for the 3 req/sec cap), the TTL response cache, and the healthCheck() function are provided in full — read production-ready application mod

                

              

                
                  
                  notion-enterprise-rbac
                  View full skill →
                
                
                  'Configure Notion enterprise access control with OAuth, workspace permissions,.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Enterprise RBAC
Overview
Implement enterprise-grade access control for Notion integrations. This covers the full OAuth 2.0 authorization flow for public integrations (multi-tenant), per-workspace token storage with encryption at rest, Notion's page-level permission model and how to handle ObjectNotFound vs RestrictedResource, an application-level role system (admin/editor/viewer) layered on top of Notion's permissions, comprehensive audit logging to a Notion database, and workspace deauthorization cleanup.
Prerequisites

Notion public integration created at  (for OAuth)
@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Database for storing per-workspace tokens (PostgreSQL, DynamoDB, etc.)
HTTPS endpoint for OAuth callback (required by Notion)

Instructions
The workflow has three steps. Each is summarized here with its key entry
point; the complete, copy-ready code for all three lives in
the full implementation reference.
Step 1: OAuth 2.0 Authorization Flow
Notion uses OAuth 2.0 for public integrations to reach external workspaces.
Build an authorization URL with a random state for CSRF protection, redirect
the user, then on callback verify the state and exchange the code for a
workspace access token. Notion's token endpoint uses HTTP Basic auth with your
client id and secret:

function getAuthorizationUrl(state: string): string {
  const params = new URLSearchParams({
    client_id: process.env.NOTION_OAUTH_CLIENT_ID!,
    response_type: 'code',
    owner: 'user',       // 'user' = user-level token, 'workspace' = workspace-level
    redirect_uri: process.env.NOTION_REDIRECT_URI!,
    state,               // CSRF protection — must verify on callback
  });
  return `https://api.notion.com/v1/oauth/authorize?${params}`;
}

The token exchange returns accesstoken, botid (the primary key per
installation), workspace_id, and owner metadata. A Python equivalent and the
full Express callback handler are in the
implementation reference.
Step 2: Token Storage and Permission-Aware API Calls
Store one token per botid (encrypt accesstoken at rest — use KMS or
column-level encryption in production), and construct a per-workspace Client
on demand. Wrap every page read so Notion's permission model is handled
explicitly rather than crashing:

/

                

              

                
                  
                  notion-hello-world
                  View full skill →
                
                
                  'Create a minimal working Notion API example.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Hello World
Overview
Three minimal examples covering the Notion API core surfaces: searching for pages, creating a test page in a database, and verifying the created page by retrieving it back.
Prerequisites

Completed notion-install-auth setup
NOTION_TOKEN environment variable set (internal integration token from )
At least one database shared with your integration via the Connections menu
Node.js 18+ with @notionhq/client or Python 3.8+ with notion-client

Authentication
Every request authenticates with your internal integration token via the
NOTION_TOKEN environment variable — the client reads it as
new Client({ auth: process.env.NOTION_TOKEN }) (or Python's
Client(auth=os.environ["NOTION_TOKEN"])). Generate the token at
notion.so/my-integrations, then share each
target database with the integration through its Connections menu. Never hardcode
the token — keep it in the environment. See notion-install-auth for the full setup.
Instructions
The workflow is three steps against the Notion API core surfaces. Instantiate the
client once, then search, create, and verify. Step 1's skeleton is below; the full
create + verify code (with block content, title extraction, and metadata) is in
the implementation walkthrough.
Step 1: Search for pages
The search endpoint queries across everything your integration can access;
filter narrows to pages (use value: 'database' for databases).

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const { results } = await notion.search({
  query: 'meeting notes',
  filter: { property: 'object', value: 'page' },
  page_size: 5,
});

Step 2: Create a test page
pages.create adds a row to a target database. The properties object must match
the database schema — Name with type title is the only universally required
property. An optional children array appends block content (headings, paragraphs,
to-dos) at creation time. Full code is in the
implementation walkthrough.
Step 3: Verify by retrieving the page
pages.retrieve fetches the full page object, confirming creation and exposing
createdtime, lastedited_time, url, and the complete properties map. Full
code is in the 
                

              

                
                  
                  notion-incident-runbook
                  View full skill →
                
                
                  Execute Notion incident response procedures with triage, mitigation, and postmortem.
                  
                      ReadBash(kubectl:*)Bash(curl:*)
                    
                
                
                  Notion Incident Runbook
Overview
Rapid incident response for Notion API failures. This runbook drives a sub-5-minute
triage that classifies the failure as Notion-side vs. integration-side, then routes to
per-error-type mitigation, cached fallback, and a structured postmortem.
Deep material — full triage scripts, remediation code, and templates — lives in
references/; this file is the high-level flow you follow live.
Prerequisites

Access to application monitoring dashboards and log aggregator
NOTION_TOKEN environment variable set for diagnostic API calls
curl and jq installed for quick CLI triage
Python alternative: notion-client (pip install notion-client)
Communication channels configured (Slack webhook, PagerDuty, etc.)

Instructions
Step 1: Quick Triage (Under 5 Minutes)
At first alert, decide whether the fault is Notion's or yours. Check the platform
status page, then test your own auth. This one call is enough to start:

curl -sf -o /dev/null -w "%{http_code}" \
  https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28"   # 2022-06-28 = pinned Notion API version

Map the result: 200 → integration-side, 401 → token expired/revoked, 429 →
rate limited, 000 → network/DNS. If status.notion.so shows an active incident, it
is Notion-side regardless of your auth code.
Read references/triage.md for the full notion-triage.sh
diagnostic (status page + auth + DB-query latency + auto-classification) and a
TypeScript triageNotionHealth() equivalent for in-app health checks.
Step 2: Decision Tree and Mitigation
Route the classification to a remediation path:

Notion-side outage — enable cached/fallback mode, notify users, monitor the

status page. Do NOT restart or rotate tokens.

401 token expired/revoked — regenerate at notion.so/my-integrations, update the

secret manager, restart the app.

429 rate limited — you are exceeding the 3 req/s average; find runaway loops or

webhook storms, drop concurrency to 1, add exponential backoff.

404 on known resources — pages unshared or trashed; re-share via the Connections menu.
400 validation errors — the database schema changed in the UI; re-fetch with

databases.retrieve and update property mappings.
Read references/mitigat

                

              

                
                  
                  notion-install-auth
                  View full skill →
                
                
                  'Install and configure the Notion API SDK with authentication.
                  
                      ReadEditBash(npm:*)Bash(pip:*)
                    
                
                
                  Notion Install & Auth
Overview
Set up the official Notion SDK and configure authentication for internal integrations. The Node.js SDK is @notionhq/client (npm) and the Python SDK is notion-client (pip) — both wrap the Notion API at https://api.notion.com/v1 using API version 2022-06-28.
Prerequisites

Node.js 18+ or Python 3.8+
Package manager (npm, pnpm, yarn, or pip)
A Notion account (free or paid)
Access to My Integrations dashboard

Instructions
Step 1: Create Integration and Install SDK
Create an internal integration at :

Click New integration
Name it, select the workspace, and choose capabilities (Read content, Update content, Insert content)
Copy the Internal Integration Secret (starts with ntn or secret)

Install the SDK:

# Node.js / TypeScript (official SDK)
npm install @notionhq/client

# Python (official SDK)
pip install notion-client

Step 2: Configure Authentication
Store the token in environment variables -- never hardcode it:

# Set environment variable
export NOTION_TOKEN="ntn_your_integration_secret_here"

# Or add to .env file (add .env to .gitignore)
echo 'NOTION_TOKEN=ntn_your_integration_secret_here' >> .env

Share pages with your integration: In Notion, open the page or database you want to access. Click the ... menu, select Connections, and add your integration. Without this step, all API calls return objectnotfound.
Step 3: Verify Connection

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const me = await notion.users.me({});
console.log(`Authenticated as: ${me.name} (${me.type})`);
console.log(`Bot ID: ${me.id}`);

If the bot user is returned, authentication is working.
Output

SDK package installed (@notionhq/client for Node.js, notion-client for Python)
Environment variable NOTION_TOKEN configured
Integration connected to target pages/databases via Connections menu
Verified API connectivity with users.me() call

Error Handling

Error
Cause
Solution


unauthorized
Invalid or expired token
Regenerate at notion.so/my-integrations


objectnotfound
Page not shared with integration
                
              
                
                  
                  notion-known-pitfalls
                  View full skill →
                
                
                  Use when debugging or reviewing Notion API code that fails with object_not_found, validation_error, rate_limited, or returns incomplete data.
                  
                      ReadGrep
                    
                
                
                  Notion Known Pitfalls
Overview
The twelve most common mistakes when building Notion API integrations, each with the wrong pattern, why it fails, and the correct fix. These pitfalls account for the majority of developer support questions.
The lean flow lives here; the full wrong-vs-right code for every pitfall (TypeScript and Python) is in references/implementation.md.
Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set
Familiarity with Notion API concepts (databases, pages, blocks, properties)

Authentication
All calls authenticate with an internal integration token passed to the client
constructor (new Client({ auth: process.env.NOTION_TOKEN }) /
Client(auth=os.environ["NOTION_TOKEN"])). The token alone is not enough —
every page and database must also be explicitly shared with the integration in
the Notion UI (Pitfall #1). Never hardcode the token; read it from the
environment.
Instructions
Work the pitfalls in order of frequency. Pitfall #1 is the single most common error, so it is worked in full below; #2–#12 follow the same wrong-vs-right shape and the complete code is in references/implementation.md.
Step 1: Not Sharing Pages with the Integration (Pitfall #1)
The single most common Notion API error. Every page/database must be explicitly shared with your integration. A 404 objectnotfound does NOT mean the page is missing — it means your integration lacks access.

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

// This returns 404 even though the page EXISTS in your workspace
try {
  const page = await notion.pages.retrieve({ page_id: 'some-page-id' });
} catch (error) {
  if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) {
    // "object_not_found" does NOT mean the page doesn't exist
    // It means your integration doesn't have access
    console.error('Page exists but integration lacks access.');
    console.error('Fix: In Notion UI, open page -> ... menu -> Connections -> Add your integration');
    console.error('Tip: Share a parent page to grant access to ALL child pages');
  }
}

// Always verify access at startup
async function verifyAccess(databaseId: string): Promise<boolean> {
  try {
    await notion.databases.retrieve({ database_id: databaseId });
    return true;
  } catch {
    console.error(`Cannot access dat

                

              

                
                  
                  notion-load-scale
                  View full skill →
                
                
                  Use when you must move high volumes through the Notion API without tripping its 3 req/sec limit — bulk-creating pages, syncing 100K+ record databases, or running background jobs.
                  
                      ReadWriteBash(node:*)Bash(npx:*)
                    
                
                
                  Notion Load & Scale
Overview
Patterns for high-volume Notion API usage within the 3 requests/second rate
limit. Covers parallel request orchestration with p-queue, worker queue
architecture for background processing, full database pagination at scale
(100K+ records), incremental sync using lasteditedtime filters to avoid
re-fetching unchanged data, and memory management for bulk operations via
streaming and chunked processing.
Full runnable TypeScript + Python implementations for all three steps live in
references/implementation.md; planning utilities
live in references/examples.md.
Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
p-queue for rate-limited concurrency (npm install p-queue)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN set (each token gets its own 3 req/s limit)
Test database in Notion (dedicated for load testing)

Authentication
All operations authenticate with a Notion internal integration token in the
NOTION_TOKEN environment variable; the SDKs send it as a Bearer token
automatically. Each token has an independent 3 req/s limit — the key lever
for horizontal scaling. Full auth notes, including raw curl headers, are in
references/implementation.md.
Instructions
The three patterns compose: rate-limited calls (Step 1) are the primitive the
worker queue (Step 2) and the streaming paginator (Step 3) both build on. Read
the lean summary here, then open
references/implementation.md for the complete
code.
Step 1: Parallel Requests Within Rate Limits
Notion enforces 3 requests/second per integration token. Drive every call
through a single p-queue tuned to interval: 340 / intervalCap: 1 (~3/s
with a safety margin) rather than relying on concurrency alone, and wrap each
call so a rate_limited (429) response honors retry-after and retries once.

import PQueue from 'p-queue';

const apiQueue = new PQueue({ concurrency: 1, interval: 340, intervalCap: 1 });

// Every Notion call goes through this queue; add 429 retry inside (see refs).
const results = await Promise.all(
  dbIds.map(id => apiQueue.add(() =>
    notion.databases.query({ database_id: id, page_size: 100 })
  ))
);

Full wrapper (metrics, retry-after handling, Python token-bucket v
                
              

                
                  
                  notion-local-dev-loop
                  View full skill →
                
                
                  Configure Notion local development with a dedicated dev integration, test mocking, and hot reload.
                  
                      ReadWriteBash(npm:*)Bash(pnpm:*)
                    
                
                
                  Notion Local Dev Loop
Overview
Set up a fast, reproducible local development workflow for Notion integrations. This skill creates a
dedicated dev integration with its own token, structures the project for testability, mocks the
Notion SDK in unit tests, and runs gated integration tests against a sandboxed dev workspace — so
production data stays safe while you iterate quickly.
Prerequisites

Completed notion-install-auth setup (you have a working Notion integration)
Node.js 18+ with npm/pnpm, or Python 3.10+
A Notion workspace where you can create test pages and databases

Authentication
This workflow uses a separate dev integration token, never the production token. The Notion SDK
reads NOTIONTOKEN from the environment automatically. Store the dev token (prefix ntn) in a
git-ignored .env.development and commit a .env.example template so teammates know which variables
to fill in. Token creation is covered by the notion-install-auth skill; Step 1 below wires it into
the dev sandbox.
Instructions
Step 1: Create a Dev Integration and Workspace Sandbox
Create a separate integration exclusively for development so writes can never touch production data.

Go to Settings & Members > Connections > Develop or manage integrations (or visit developers.notion.com)
Click New integration and name it My App — Dev
Copy the token (starts with ntn_) into .env.development
Create a dedicated Dev Workspace page (or a top-level "Dev Testing" page) and share it with the dev integration
Inside that page, create test databases that mirror your production schema


# .env.development — git-ignored, dev only
NOTION_TOKEN=ntn_dev_xxxxxxxxxxxxxxxxxxxx
NOTION_TEST_DATABASE_ID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
NOTION_TEST_PAGE_ID=ffffffff-0000-1111-2222-333333333333

# .env.example — commit this as a template
NOTION_TOKEN=ntn_your_dev_token_here
NOTION_TEST_DATABASE_ID=your_test_db_id
NOTION_TEST_PAGE_ID=your_test_page_id

Recommended project layout — a notion/ module the app imports, and split unit/integration tests:

my-notion-project/
├── src/
│   ├── notion/
│   │   ├── client.ts          # Singleton with retry + rate-limit awareness
│   │   ├── queries.ts         # Database query wrappers
│   │   └── helpers.ts         # Property extractors, rich text builders
│   └── index.ts
├── tests/
│   ├── unit/
│   │   └── notion.test.ts     # Mocked SDK tests
│   └── integration/
│       └── notion.test.ts     # Live API tests (gated)
├── .env.development           

                

              

                
                  
                  notion-migration-deep-dive
                  View full skill →
                
                
                  'Migrate data to/from Notion or between Notion workspaces with data mapping.
                  
                      ReadBash(npm:*)Bash(node:*)
                    
                
                
                  Notion Migration Deep Dive
Overview
Production migration patterns for moving data to, from, and between Notion workspaces — rate-limited bulk import, paginated export, cross-platform conversion, and post-migration validation. Every bulk-write path respects Notion's 3 requests/second average rate limit.
Prerequisites

@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
p-queue for rate-limited concurrency (npm install p-queue)
Source data access (CSV files, Confluence API, Google Docs API, etc.)
Target Notion database(s) created with matching property schema

Authentication: create a Notion internal integration at
notion.so/my-integrations, share the
target database(s) with it, and export the secret as NOTION_TOKEN. Every code
sample reads process.env.NOTION_TOKEN — the client never takes an inline
credential.
Instructions
The workflow has three directions. Each step below gives the essential shape;
the full runnable code lives in the reference files so this page stays scannable.
Step 1: Import CSV/JSON into a Notion database
Map each source field to a Notion property value object, strip properties the
target schema does not have, and create pages through a rate-limited queue:

const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 3 }); // ≤3 req/s

await notion.pages.create({
  parent: { database_id: databaseId },
  properties: {
    Name: { title: [{ text: { content: record.name || 'Untitled' } }] },
    Status: { select: { name: record.status || 'Not Started' } },
  },
});

Validate the database schema with databases.retrieve before the loop so
mismatched columns are dropped instead of failing every row. Full TypeScript +
Python importers (property mapping, schema filtering, error collection):
full walkthrough.
Step 2: Export from Notion to JSON/CSV
Page through databases.query (100 rows per page) and flatten each page's
properties by type. Optionally pull block content for rich-content migrations:

do {
  const response = await notion.databases.query({
    database_id: databaseId, page_size: 100, start_cursor: cursor,
  });
  // extractProperties() maps title/select/multi_select/date/relation/... to flat values
  cursor = response.has_more ? response.next_cursor ?? undefined : undefined;
} while (cursor);

Full exporter with the per-property-type extractor and block-content 
                
              

                
                  
                  notion-multi-env-setup
                  View full skill →
                
                
                  Configure Notion integrations across development, staging, and production environments.
                  
                      ReadWriteEditBash(aws:*)Bash(gcloud:*)Bash(vault:*)
                    
                
                
                  Notion Multi-Environment Setup
Overview
Configure separate Notion integrations for development, staging, and production. Each environment uses its own integration token, targets different databases, and applies environment-appropriate log levels and timeouts. This prevents dev data leaking into prod and enforces least-privilege per tier.
Prerequisites

Notion workspace(s) per environment (one workspace can serve dev/staging via separate integrations)
@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Secret management platform (AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault)
CI/CD pipeline with per-environment variable injection

Instructions
The build has three steps. The lean skeleton below is enough to follow the workflow end to end; the full walkthrough carries the complete TypeScript and Python factories, every secret-manager command, and the CI/CD workflow.
Step 1: Per-environment integrations and an env-aware client
Create one integration per environment at , each with capabilities scoped to the tier — dev gets full access, prod gets the minimum required:

Environment
Integration
Capabilities
Timeout
Log Level


Development
my-app-dev
All (read+update+insert+delete)
60s
DEBUG


Staging
my-app-staging
Read + Update + Insert
30s
WARN


Production
my-app-prod
Minimum required only
30s
ERROR


A single client factory reads NODEENV (or APPENV), pulls the token and database IDs from the environment, and applies the per-tier log level and timeout. It throws a descriptive error when NOTION_TOKEN is missing so misconfiguration fails loudly:

export function createNotionClient(): Client {
  const config = getConfig(); // reads NODE_ENV, token, per-tier defaults
  return new Client({
    auth: config.token,
    logLevel: config.logLevel,
    timeoutMs: config.timeoutMs,
  });
}

Full TypeScript getConfig/getDatabaseId and the Python equivalent: implementation.md, Step 1.
Step 2: Secret management and environment files
Keep dev/staging tokens in git-ignored per-environment files (.env.development, .env.staging). Never store production tokens in files — put them in a secret manager and inject at 
                
              

                
                  
                  notion-observability
                  View full skill →
                
                
                  'Set up observability for Notion integrations with metrics, traces, and.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Observability
Overview
Instrument Notion API calls with metrics, structured logging, and alerting. Track request rates, latencies, error rates, and rate limit headroom across a full observability stack: an instrumented client wrapper, Prometheus metrics, structured logging via pino, health check endpoints, and alerting rules.
Prerequisites

@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Prometheus-compatible metrics backend (optional: Grafana, Datadog, or CloudWatch)
Structured logging library: pino (Node.js) or structlog (Python)

Authentication
All snippets read the integration token from the NOTION_TOKEN environment variable (never hard-code it) and pass it as auth to the Notion client constructor. Store it in your secret manager and inject it at runtime. The health check and metrics endpoints below expose no secrets — only aggregate counters and status.
Instructions
The workflow layers three pieces. Build them in order; each is self-contained. Full code for every step lives in references/implementation.md.
Step 1: Instrumented client wrapper
Wrap every Notion call so timing, error classification, rate-limit detection, and structured logging happen automatically. The wrapper accumulates per-operation latency buckets and exposes getMetrics() for avg/p95. Skeleton:

class InstrumentedNotionClient {
  async call<T>(operation: string, fn: (c: Client) => Promise<T>): Promise<T> {
    const start = performance.now();
    try {
      const result = await fn(this.client);
      this.recordLatency(operation, Math.round(performance.now() - start));
      return result;
    } catch (error) {
      if (isNotionClientError(error) && error.code === APIErrorCode.RateLimited) {
        this.metrics.rateLimitCount++;
      }
      throw error;
    }
  }
}

A Python (notion-client) equivalent is in the reference. Full TypeScript + Python wrappers: references/implementation.md (Step 1).
Step 2: Prometheus metrics export
Register a request counter, a latency histogram (buckets tuned for Notion's typical 200-800ms responses), an error counter keyed by error code, and a rate-limit gauge. Wrap calls with startTimer() and expose a /metrics endpoint for scraping. Full export code: references/implementation.md (Step 2).
Step 3: Health check, structured logging, and alerting
Add a /health/notion endpoint that probes users.me and returns 200/503 with
                
              

                
                  
                  notion-performance-tuning
                  View full skill →
                
                
                  'Optimize Notion API performance with caching, batching, parallel requests,.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Performance Tuning
Overview
Optimize Notion API performance by minimizing API calls, caching responses with TTL-based invalidation, batching block appends, parallelizing requests within rate limits, selecting only needed properties, and implementing incremental sync patterns. Target latency benchmarks: Database Query p50=150ms, Page Create p50=200ms, Search p50=300ms.
Prerequisites

@notionhq/client installed (npm install @notionhq/client)
p-queue for rate-limited parallelism (npm install p-queue)
lru-cache for TTL-based caching (npm install lru-cache)
Authentication: a Notion integration token in NOTIONTOKEN (internal integration secret from ), passed as new Client({ auth: process.env.NOTIONTOKEN })
Understanding of your access patterns (read-heavy vs write-heavy)
Optional: Redis or ioredis for distributed caching across instances

Instructions
Apply the three techniques in order — each builds on the previous one. The lean
skeletons below are enough to follow the workflow; drill into the linked
reference files for the complete, copy-paste-ready code.
Step 1: Minimize API Calls and Reduce Payload
Avoid N+1 patterns, page with pagesize: 100 (the maximum), select only the properties you need with filterproperties, and batch block appends in chunks of 100.

// Batch block appends — up to 100 blocks per request (API maximum)
for (let i = 0; i < blocks.length; i += 100) {
  await notion.blocks.children.append({
    block_id: pageId,
    children: blocks.slice(i, i + 100),
  });
}

See full implementation walkthrough for the N+1-vs-batched query comparison, filter_properties usage, and selective block-tree expansion.
Step 2: Cache Responses with TTL-Based Invalidation
Use an LRU cache with per-operation TTLs (short for volatile data like search, longer for stable data like schemas) and invalidate entries on every write to keep reads consistent.

import { LRUCache } from 'lru-cache';
const cache = new LRUCache<string, any>({ max: 1000, ttl: 60_000, allowStale: false });
// Invalidate on write: for (const key of cache.keys())
//   if (key.startsWith(`db:${dbId}:`)) cache.delete(key);

See full implementation walkthrough for tiered TTL configuration, cursor-based cached pagination, write-through invalidation, and cache-stats monitoring.
Step 3: Parallel Requests with Rate-Limited Queue and Latency Monitoring
See 
                

                  
                  notion-policy-guardrails
                  View full skill →
                
                
                  Use when you need to govern Notion integrations at scale — set integration naming standards, enforce page sharing policies, standardize property naming and database schemas, and run access audits that scan which bots can reach which pages.
                  
                      ReadWriteEditBash(npx:*)Bash(node:*)
                    
                
                
                  Notion Policy & Guardrails
Overview
Governance framework for Notion integrations at scale. Covers integration
naming standards, page sharing policy enforcement, property naming conventions,
database schema validation, and access audit scripts. Uses Client from
@notionhq/client for programmatic enforcement.
Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set (admin-level integration recommended for audits)
CI/CD pipeline (GitHub Actions examples provided)

Authentication
All scripts authenticate with a Notion internal integration token read from
the NOTION_TOKEN environment variable — never hardcode it. Create the token at
notion.so/my-integrations, share the target pages/databases with the integration,
and inject the token via CI secrets (e.g. secrets.NOTIONAUDITTOKEN). Audit
scripts want a broadly-shared admin integration; runtime bots want the narrowest
sharing scope that works. Token rotation is tracked in Step 1 (max 90 days).
Instructions
The workflow has three stages. Each stage's full enforcement code (TypeScript +
Python) lives in references/implementation.md —
the skeletons below show the shape; drill into the reference for the complete
functions.
Step 1: Integration Naming Standards and Token Management
Establish a {team}-{env}-{purpose} naming convention (e.g. eng-prod-sync) so
teams can identify which bot accessed what, validate it at startup, and track
token rotation (max 90 days). Core check:

// Must match: /^[a-z]+-[a-z]+-[a-z]+$/  →  eng-prod-sync
function validateIntegrationName(name: string): string[] { /* ... */ }

Full IntegrationConfig, startup validation, and checkTokenExpiry registry:
references/implementation.md § Step 1.
Step 2: Page Sharing Policies and Property Naming Conventions
Standardize property names across databases (PascalCase titles, Date/At
suffixes on dates, plural multi-selects, a banned-name list) and audit which
pages are shared publicly. Core check:

async function auditDatabaseSchema(notion, databaseId):
  Promise<{ violations: string[]; recommendations: string[] }> { /* ... */ }

Full PROPERTYNAMINGRULES, auditPageAccess, and the Python port:

                

              

                
                  
                  notion-prod-checklist
                  View full skill →
                
                
                  Execute a Notion API production deployment checklist and readiness verification.
                  
                      ReadWriteBash(grep:*)Bash(curl:*)Bash(jq:*)
                    
                
                
                  Notion API Production Deployment Checklist
Overview
A structured 12-section checklist for deploying Notion API integrations to production, covering authentication security, capability scoping, page sharing, rate limits, pagination, error handling, versioning, retries, monitoring, graceful degradation, data validation, and OAuth token lifecycle. Each section maps to a specific failure mode seen in production Notion integrations, and every item is testable — the skill produces a verified pass/fail report, not aspirational guidance.
Prerequisites

Node.js 18+ with @notionhq/client v2.x installed
Working Notion integration tested in a development workspace
Production Notion API token (internal) or OAuth credentials (public integration)
Target databases and pages identified by ID
Deployment platform configured (Vercel, Railway, AWS, etc.)

Verify SDK is installed:

node -e "const { Client } = require('@notionhq/client'); console.log('SDK loaded')" 2>/dev/null \
  || echo "MISSING: npm install @notionhq/client"

Instructions
Work through the checklist in order, marking each item pass or fail. A single fail in sections 1-6 is a deployment blocker.

Run the pre-deploy smoke test (see Examples) to confirm the token is set, auth works, and target databases are reachable. This catches the most common failure — a page that is not shared with the integration — before you go deeper.
Grade each of the 12 sections against its checkbox items. The summary table below is the map; the full item-by-item detail, fail criteria, and code snippets live in references/checklist-sections.md.
Pull implementation patterns (rate-limited queue, paginator, typed error handler, retry, cache fallback, property validator, OAuth exchange) from references/code-examples.md as each section requires them.
Record a pass/fail per section and total the blocking (1-6) vs non-blocking (7-12) failures.
Emit the readiness report (see Output) with the final verdict: ready to deploy, or blocked with the count of items to fix.

The 12 sections at a glance

                
              
                
                  
                  notion-rate-limits
                  View full skill →
                
                
                  'Manage Notion API rate limits with exponential backoff, queue-based.
                  
                      ReadWriteEditBash(npm:*)GlobGrep
                    
                
                
                  Notion Rate Limits
Overview
The Notion API enforces 3 requests per second per integration token across all endpoints and tiers. Exceeding this returns HTTP 429 with a Retry-After header. Detect with isNotionClientError() + APIErrorCode.RateLimited, implement exponential backoff with jitter, and use queue-based throttling for high-throughput workloads.
Prerequisites

@notionhq/client v2.x (TypeScript) or notion-client (Python)
Integration token in NOTION_TOKEN from notion.so/my-integrations
For queue patterns: p-queue v8+ (npm install p-queue)

Instructions
Step 1 — Detect Rate Limits and Apply Exponential Backoff

#
Section
Blocking?
Fails if


1
Token in env vars (never hardcoded)
Yes
Token found in source, git history, or client bundle


2
Minimum required capabilities
Yes
Integration has scopes it does not use


3
Target pages/DBs shared with integration

Aspect
Value


Rate limit
3 req/s per integration token (all tiers)


Throttle response
HTTP 429 + Retry-After header (seconds)


Scope
Per token, not per user or workspace


Max block children
1,000 per blocks.children.append


Max page size
100 results per paginated request


The SDK retries 429 automatically (2 retries, 3 total attempts). For heavier workloads, use custom backoff that honors Retry-After and adds jitter to prevent thundering herd:

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function withBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5, baseMs = 1000, maxMs = 32_000
): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try { return await fn(); }
    catch (err) {
      if (i === maxRetries) throw err;
      if (isNotionClientError(err) && err.code === APIErrorCode.RateLimited) {
        const wait = parseInt((err as any).headers?.['retry-after'] ?? '1', 10);
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }
      if (isNotionClientError(err) && err.status && err.status < 500) throw err;
      const delay = Math.min(baseMs * 2 ** i + Math.random() * 500, maxMs);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Exhausted retries');
}

Step 2 — Throttle with Queue-Based Request Management
Enforce the 3 req/s limit at the application level instead of relying on 429 responses:

import PQueue from 'p-queue';

const queue = new PQueue({
  concurrency: 3, interval: 1000, intervalCap: 3,
  carryoverConcurrencyCount: true,
});

async function throttled

                

              

                
                  
                  notion-reference-architecture
                  View full skill →
                
                
                  Design and implement a production-ready Notion integration architecture with proper layering, caching, error handling, and testing strategies.
                  
                      ReadWriteEditBash(npm:*)Bash(npx:*)
                    
                
                
                  Notion Reference Architecture
Overview
Production-grade architecture for Notion integrations using @notionhq/client.
This skill defines a four-layer architecture — client singleton, repository
pattern, service layer, and caching — that scales from simple scripts to
enterprise applications, with multi-integration setups, event-driven
processing, and testing strategies.
Notion API version: 2022-06-28 | Rate limit: 3 requests/second per integration | Max page size: 100
Prerequisites

Node.js 18+ with TypeScript strict mode enabled
@notionhq/client v2.x installed (npm install @notionhq/client)
A Notion internal integration created at 
NOTION_TOKEN environment variable set with the integration token
Target databases/pages shared with the integration via "Add connections"

Instructions
Build the architecture in four layers, bottom-up. Each layer depends only on
the ones below it, so wire them in order. The full copy-ready code for every
layer lives in the implementation reference —
scaffold the project layout first, then follow
the steps below.
Step 1: Client singleton with retry and rate limiting
Wrap @notionhq/client in a singleton with explicit rate limiting (Notion caps
at 3 req/s per integration) and exponential-backoff retry. Expose separate
reader and writer clients so a read-heavy and a write-scoped integration can run
side by side and double effective throughput.

// src/notion/client.ts — skeleton (full code in the implementation reference)
export function getReaderClient(): Client { /* singleton, NOTION_READER_TOKEN ?? NOTION_TOKEN */ }
export function getWriterClient(): Client { /* singleton, NOTION_WRITER_TOKEN ?? NOTION_TOKEN */ }
export async function rateLimitedCall<T>(fn: () => Promise<T>): Promise<T> { /* 3 req/s window */ }
export async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> { /* backoff */ }

See the full singleton, rate limiter, and retry wrapper in
the implementation reference (Step 1).
Step 2: Repository and service layers
The repository layer wraps raw Notion API calls with pagination (Notion caps at
100 results per request), type extraction, and error handling. The service layer
sits above it with business logic, schema validation, and cache-aware
operations. Keep API shape in the repository and domain rules in the service so
each is independently testable.

                
              

                
                  
                  notion-reliability-patterns
                  View full skill →
                
                
                  'Graceful degradation when Notion is down: offline cache, retry with.
                  
                      ReadWriteEdit
                    
                
                
                  Notion Reliability Patterns
Overview
Production reliability patterns for Notion integrations: retry with exponential backoff, a circuit breaker to prevent cascade failures, and graceful degradation (offline cache, health checks, fallback content) so users see stale data instead of errors when the API is unreachable. All patterns use Client from @notionhq/client and handle Notion-specific error codes.
The three layers compose in order — retry sits inside the circuit breaker, which sits inside the cache/fallback layer. Read the skeletons below to follow the workflow, then open references/implementation.md for the complete copy-paste code.
Prerequisites

@notionhq/client v2.x installed (npm install @notionhq/client)
lru-cache for in-memory caching (npm install lru-cache)
Python: notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set
Understanding of circuit breaker and retry patterns

Authentication
All patterns authenticate with a Notion internal integration token read from the NOTIONTOKEN environment variable — new Client({ auth: process.env.NOTIONTOKEN }) (TS) or Client(auth=os.environ["NOTION_TOKEN"]) (Python). Never hardcode the token; the health check calls notion.users.me() to confirm the token is valid and the API reachable.
Instructions
Build the three layers in order. Each skeleton shows the shape; the full implementation lives in references/implementation.md.
Step 1: Retry with Exponential Backoff
Classify errors as transient (429, 500, 502, 503, timeouts, network) vs permanent (400/401/404), retry only the transient ones with exponential backoff + jitter, and honor the Retry-After header on rate limits.

async function retryWithBackoff<T>(fn: () => Promise<T>, opts = {}): Promise<T> {
  // maxRetries=4, baseDelayMs=1000. Loop; on transient error wait
  // baseDelayMs * 2^attempt (+ jitter), else rethrow. See implementation.md.
}

Full code (TypeScript + Python, including isTransientError and rate-limit handling): references/implementation.md Step 1.
Step 2: Circuit Breaker to Prevent Cascade Failures
During a sustained outage, stop hammering the API and fail fast. The breaker moves closed → open after N consecutive transient failures, waits a reset timeout, then tests recovery in half-open before returning to closed.

class NotionCircuitBreaker {
  // failureThreshold=5, rese

                

              

                
                  
                  notion-sdk-patterns
                  View full skill →
                
                
                  Apply production-ready @notionhq/client SDK patterns for TypeScript and Python.
                  
                      ReadWriteEditGrep
                    
                
                
                  Notion SDK Patterns
Overview
Production-ready patterns for the official Notion SDK (@notionhq/client for TypeScript, notion-client for Python) covering client initialization, database queries with filters and sorts, cursor-based pagination, rich text construction, block manipulation, and type-safe error handling using SDK error codes.
The full workflow lives in three steps below. Each step shows the essential skeleton inline; deep variants (compound filters, generic pagination helpers, block manipulation, exhaustive error switches) are in references/patterns.md, and copy-paste task recipes are in references/examples.md.
Prerequisites

Node.js 18+ with @notionhq/client v2.x installed, or Python 3.9+ with notion-client
A Notion integration token (NOTION_TOKEN) from notion.so/my-integrations
Target databases/pages shared with the integration (Share > Invite > select your integration)
TypeScript 5+ with strict mode enabled (for TypeScript patterns)

Instructions
Step 1 — Initialize the Client and Query Databases
Set up the SDK client and execute a filtered, sorted database query.
TypeScript:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const response = await notion.databases.query({
  database_id,
  filter: {
    property: 'Status',
    select: { equals: 'Active' },
  },
  sorts: [{ property: 'Created', direction: 'descending' }],
});

Python:

from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

results = notion.databases.query(
    database_id=db_id,
    filter={"property": "Status", "select": {"equals": "Active"}},
    sorts=[{"property": "Created", "direction": "descending"}],
)

For and/or compound filters and multi-key sorts, see the Compound Filters section of references/patterns.md.
Step 2 — Paginate Results and Manipulate Blocks
The Notion API returns at most 100 results per request. Loop on the cursor to retrieve every record:

let cursor: string | undefined;
do {
  const { results, next_cursor, has_more } = await notion.databases.query({
    database_id,
    start_cursor: cursor,
  });
  for (const page of results) {
    console.log(page.id);
  }
  cursor = has_more && next_cursor ? next_cursor : undefined;
} while (cu

                

              

                
                  
                  notion-search-retrieve
                  View full skill →
                
                
                  'Search Notion workspaces and retrieve pages, databases, and block content.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Notion Search & Data Retrieval
Overview
Search across a Notion workspace, query databases with compound filters, retrieve individual pages, and extract nested block content. Covers the full read path: workspace-level search, database queries with filter/sort/pagination, page retrieval, and recursive block tree traversal.
Prerequisites

@notionhq/client installed (npm install @notionhq/client)
Notion integration token with read access to target pages/databases
Integration added to target pages via the Share menu in Notion
Completed notion-install-auth setup

Instructions
Step 1: Search the Workspace
Call notion.search() to find pages and databases. The integration only sees content explicitly shared with it.

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Search for pages matching a query
const searchResults = await notion.search({
  query: 'meeting notes',
  filter: {
    property: 'object',
    value: 'page',        // 'page' or 'database'
  },
  sort: {
    direction: 'descending',
    timestamp: 'last_edited_time',
  },
  page_size: 20,
});

for (const result of searchResults.results) {
  if (result.object === 'page' && 'properties' in result) {
    const titleProp = Object.values(result.properties)
      .find(p => p.type === 'title');
    const title = titleProp?.type === 'title'
      ? titleProp.title.map(t => t.plain_text).join('')
      : 'Untitled';
    console.log(`${title} (${result.id})`);
  }
}

An empty query string returns all shared content. Results are eventually consistent — newly shared pages may take a few seconds to appear in the index.
Step 2: Query Databases with Filters
Call notion.databases.query() for structured queries. Filters support compound and/or logic. See filter-operators.md for every property type and operator.

// Single filter
const activeItems = await notion.databases.query({
  database_id: 'your-database-id',
  filter: {
    property: 'Status',
    select: { equals: 'Active' },
  },
  sorts: [
    { property: 'Priority', direction: 'descending' },
  ],
  page_size: 50,
});

// Compound filter with AND
const highPriorityActive = await notion.databases.query({
  database_id: 'your-database-id',
  filter: {
    and: [
      { property: 'Status', select: { equals: 'Active' } },
      { property: 'Priority', number: { greater_than: 3 } },
    ],
  },
});

Step 3: Paginate, Retrieve Pages,
                
              

                
                  
                  notion-security-basics
                  View full skill →
                
                
                  Apply Notion API security best practices for integration tokens, OAuth2 flows, least-privilege capabilities, and page-level access control.
                  
                      ReadWriteBash(npm:*)Bash(curl:*)
                    
                
                
                  Notion Security Basics
Overview
Security fundamentals for the Notion API: integration token management, internal vs public integration models, principle of least privilege for capabilities, page-level access auditing, token rotation, OAuth2 flows for public integrations, and webhook verification. All examples use @notionhq/client v2.x and target the 2022-06-28 API version.
This SKILL.md gives you the workflow at a high level with the essential skeletons inline. Drill into the linked references for the full code:

Token storage, secret scanning, and access auditing — Step 1 + Step 2 in full
Token rotation, OAuth2, and webhook verification — Step 3 in full
Worked examples — dual-integration .env + startup validation script

Prerequisites

Notion integration created at notion.so/my-integrations
Node.js 18+ with @notionhq/client installed (npm install @notionhq/client)
Understanding of environment variables and .env file patterns
For public integrations: OAuth2 client ID and secret from the integration dashboard

Instructions
Step 1: Secure Token Storage and .env Management
Integration tokens are secrets with the same sensitivity as database passwords. Notion tokens use the ntn prefix (current) or secret prefix (legacy). Both grant full access to every page shared with the integration. Two rules: never hardcode a token, and gitignore every .env variant BEFORE creating one.
Load from the environment and validate the token format before use:

import { Client } from '@notionhq/client';

const token = process.env.NOTION_TOKEN;
if (!token) throw new Error('NOTION_TOKEN is required (see notion.so/my-integrations).');
if (!token.startsWith('ntn_') && !token.startsWith('secret_')) {
  throw new Error('NOTION_TOKEN has an unexpected format (expected ntn_ or legacy secret_).');
}

const notion = new Client({ auth: token });

Add a CI secret-scan step (grep -rE "(ntn|secret)[a-zA-Z0-9]{30,}") so an accidentally committed token fails the build. Full .gitignore patterns, the .env.example template, and the complete GitHub Actions workflow are in token storage, secret scanning, and access auditing.
Step 2: Least-Privilege Capabilities and Access Auditing
Configure integration capabilities at the integration dashboard. Each integration should reque
                
              

                
                  
                  notion-upgrade-migration
                  View full skill →
                
                
                  'Upgrade @notionhq/client SDK versions and migrate between Notion API.
                  
                      ReadWriteEditBash(npm:*)Bash(pip:*)Bash(git:*)GlobGrep
                    
                
                
                  Notion Upgrade & Migration
Overview
Step-by-step guide for upgrading @notionhq/client (Node.js) and notion-client (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version 2022-06-28 and the SDK feature timeline through v2.x.
The workflow is three phases — audit what you run today, upgrade on an isolated branch while fixing breaking changes, then verify every API surface before merging. Deep code (the full breaking-change catalog, the verification suite, and worked recipes) lives in references/ so this file stays a scannable playbook.
Prerequisites

Existing project with @notionhq/client or notion-client installed
Git repository with clean working tree (no uncommitted changes)
Test suite covering Notion API calls (or willingness to add verification tests)
NOTION_TOKEN environment variable configured

Instructions
Step 1: Audit Current Versions and API Surface
Determine what you are running today before changing anything.

# Node.js — installed vs latest SDK version
npm ls @notionhq/client
npm view @notionhq/client version

# Python — installed vs latest SDK version
pip show notion-client 2>/dev/null | grep Version
pip index versions notion-client 2>/dev/null | head -1

# Find which API version your code specifies
grep -rn "notionVersion\|Notion-Version\|notion_version" src/ lib/ app/ 2>/dev/null

Record the current SDK version and API version before proceeding. If no notionVersion is set explicitly, the SDK uses its built-in default (typically 2022-06-28 for current releases).
SDK version history — key milestones:

SDK Version
Notable Additions


2.2.0
Comments API support (notion.comments.create, notion.comments.list)


2.2.3
Status property type in database schemas


2.2.4
Unique ID property, verification property


2.2.13
Improved TypeScript discriminated unions for block types


2.2.15
Current stable — bug fixes, dependency updates


API version timeline:

                
                  
                  notion-webhooks-events
                  View full skill →
                
                
                  'Build change detection and event handling for Notion workspaces using.
                  
                      ReadWriteEditBash(node:*)Bash(npx:*)Bash(npm:*)Bash(curl:*)
                    
                
                
                  Notion Webhooks & Event Handling
Overview
Notion offers three approaches to change detection, each with different trade-offs:

API Version
Key Changes


2022-02-22
Rich text standardization, consistent pagination


2022-06-28
Current stable — most tutorials and production apps use this

                
              

Approach
Latency
Complexity
Reliability


Polling with search / databases.query
30s-5min (your poll interval)
Low
High — you control timing


Native webhooks (API 2025-02+)
Near real-time
Medium
Good — requires HTTPS endpoint, retry handling


Third-party connectors (Zapier, Make)
1-15 min
Low (no-code)
Vendor-dependent


Honest assessment: Notion's native webhook support arrived in mid-2025 and covers page, database, comment, and data source events. It works well for event notification but does not deliver full payloads — you still need API calls to fetch the changed data. For many use cases, especially incremental sync and backup, polling with lasteditedtime filters remains the most battle-tested pattern.
Prerequisites

@notionhq/client v2.3+ installed (npm install @notionhq/client)
Notion integration created at 
Integration shared with target pages/databases (Connections menu in Notion)
NOTION_TOKEN environment variable set to the integration's Internal Integration Secret
For native webhooks: HTTPS endpoint accessible from the internet

Authentication
All API calls authenticate with the integration's Internal Integration Secret, passed as a bearer token. The @notionhq/client handles the header when you construct the client — never hardcode the secret:

const notion = new Client({ auth: process.env.NOTION_TOKEN });

Store NOTION_TOKEN in your environment (.env, a GitHub Actions secret, or a secrets manager) and grant the integration access to each target page/database via the Connections menu.
Webhook deliveries themselves carry no bearer token — verify them with the url_verification handshake and treat the payload as untrusted, fetching the real data through the authenticated client rather than trusting the event body.
Instructions
Pick an approach from the Overview table, then follow the matching step. Steps 1 and 2 keep a runnable skeleton here and link to the full implementation in references/.
Step 1: Polling-Based Change Detection
Polling is the most reliable approach and works with every Notion API version. Use notion.search() to discover recently edited content across the entire workspace, or notion.databases.query()
                

              

          

        


      
      

      
      

      
      

      
      
  Ready to use notion-pack?
  
    
    
  




      
      
          Related Plugins
          
            
  supabase-pack
  Complete Supabase integration skill pack with 30 skills covering authentication, database, storage, realtime, edge functions, and production operations. Flagship+ tier vendor pack.
  /plugin install supabase-pack@claude-code-plugins-plus
  

  vercel-pack
  Complete Vercel integration skill pack with 30 skills covering deployments, edge functions, preview environments, performance optimization, and production operations. Flagship+ tier vendor pack.
  /plugin install vercel-pack@claude-code-plugins-plus
  

  clay-pack
  Complete Clay integration skill pack with 30 skills covering data enrichment, waterfall workflows, AI agents, and GTM automation. Flagship+ tier vendor pack.
  /plugin install clay-pack@claude-code-plugins-plus
  

  cursor-pack
  Complete Cursor integration skill pack with 30 skills covering AI code editing, composer workflows, codebase indexing, and productivity features. Flagship+ tier vendor pack.
  /plugin install cursor-pack@claude-code-plugins-plus
  

  exa-pack
  Complete Exa integration skill pack with 30 skills covering neural search, semantic retrieval, web search API, and AI-powered discovery. Flagship+ tier vendor pack.
  /plugin install exa-pack@claude-code-plugins-plus
  

  firecrawl-pack
  Complete Firecrawl integration skill pack with 30 skills covering web scraping, crawling, markdown conversion, and LLM-ready data extraction. Flagship+ tier vendor pack.
  /plugin install firecrawl-pack@claude-code-plugins-plus
  

          
        

      
      
          Tags
          
            notionsaassdkintegration
          
        
    

  


  

    

    
    
        
            
                Agent Skills in Your Inbox
                
                    
                    
                    
                
                No spam, ever. Unsubscribe with one click.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Hall of Fame
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
            

            
                Tons of Skills by Intent Solutions. Open-source plugins, agents and skills for AI coding agents.
                © 2026 Tons of Skills | Intent Solutions

Plan	Price	API Access	Rate Limit
Free	$0	Full API	3 req/sec
Plus	$12/user/mo	Full API	3 req/sec
Business	$28/user/mo	Full API	3 req/sec
Enterprise	Custom	Full API	3 req/sec