Skip to main content
skill CX Codex

notion-sdk — Claude Code skill: control Notion with Python

notion-sdk — a skill for managing Notion via the official Python SDK. Creates pages and databases, queries information, adds content blocks — all programmatically.

MIT 133 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill notion-sdk -a claude-code
Open on GitHub

What notion-sdk does

Available on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. The skill wraps the notion-client library with helper modules: create_page.py builds pages with properties, add_blocks.py appends text and code, query_database.py searches and filters. You'll need a Notion integration token (starts with ntn_ or secret_) — the agent requests it automatically. Critical requirement: each page or database you work with must be explicitly shared with the integration through Notion's connection menu.

The skill handles API constraints transparently — rate limits, automatic retries with exponential backoff, and a 0.5-second consistency delay after block creation. Pages can't be deleted via API, only archived. Supports all 24 Notion property types and block types, including formatted text, links, and mentions.

What it helps with

  • create a task in a Notion database from an agent
  • populate a Notion page with structured content and code blocks
  • query and filter records from a Notion database
  • automatically sync external data into Notion during development
  • integrate Notion as a persistent store for agent workflows

Example prompts for the agent

  • Create a page in my Tasks database called New Feature with status In Progress and due date end of month.
  • Find all incomplete high-priority tasks, sort by date, and list them.
  • Add a Test Results heading to the page, then a summary paragraph and a Python code block.

How to install notion-sdk

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill notion-sdk -a claude-code

2Manually: put the files in place

~/.claude/skills/notion-sdk/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/notion-sdk/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about notion-sdk

How do I install notion-sdk in Claude Code?

Run npx skills add terrylica/cc-skills --skill notion-sdk -a claude-code. After installation, the skill is available at ~/.claude/skills/notion-sdk/SKILL.md.

What do I need to get started?

You need a Notion integration token from notion.so/my-integrations. Then, each database or page the agent will access must be explicitly connected to that integration via Notion's connection menu — this is required.

Can I permanently delete a page via the API?

No. The API only moves pages to trash (archive). You can restore them manually from Notion.

Source text

SKILL.md · MIT
---
name: notion-sdk
description: Control Notion via Python SDK. TRIGGERS - Notion API, create page, query database, add blocks.
allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
---

# Notion SDK Skill

Control Notion programmatically using the official `notion-client` Python SDK. See [PyPI](https://pypi.org/project/notion-client/) for current version.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Creating pages or databases in Notion via API
- Querying Notion databases programmatically
- Adding blocks (text, code, headings) to Notion pages
- Automating Notion workflows with Python
- Integrating external data sources with Notion

## Preflight: Token Collection

Before any Notion API operation, collect the integration token:

```
AskUserQuestion(questions=[{
    "question": "Please provide your Notion Integration Token (starts with ntn_ or secret_)",
    "header": "Notion Token",
    "options": [
        {"label": "I have a token ready", "description": "Token from notion.so/my-integrations"},
        {"label": "Need to create one", "description": "Go to notion.so/my-integrations → New integration"}
    ],
    "multiSelect": false
}])
```

After user provides token:

1. Validate format (must start with `ntn_` or `secret_`)
2. Test with `validate_token()` from `scripts/notion_wrapper.py`
3. Remind user: **Each page/database must be shared with the integration**

## Quick Start

### 1. Create a Page in Database

```python
from notion_client import Client
from scripts.create_page import (
    create_database_page,
    title_property,
    status_property,
    date_property,
)

client = Client(auth="ntn_...")
page = create_database_page(
    client,
    data_source_id="abc123...",  # Database ID
    properties={
        "Name": title_property("My New Task"),
        "Status": status_property("In Progress"),
        "Due Date": date_property("2025-12-31"),
    }
)
print(f"Created: {page['url']}")
```

### 2. Add Content Blocks

```python
from scripts.add_blocks import (
    append_blocks,
    heading,
    paragraph,
    bullet,
    code_block,
    callout,
)

blocks = [
    heading("Overview", level=2),
    paragraph("This page was created via the Notion API."),
    callout("Remember to share the page with your integration!", emoji="⚠️"),
    heading("Tasks", level=3),
    bullet("First task"),
    bullet("Second task"),
    code_block("print('Hello, Notion!')", language="python"),
]
append_blocks(client, page["id"], blocks)
```

### 3. Query Database

```python
from scripts.query_database import (
    query_data_source,
    checkbox_filter,
    status_filter,
    and_filter,
    sort_by_property,
)

# Find incomplete high-priority items
results = query_data_source(
    client,
    data_source_id="abc123...",
    filter_obj=and_filter(
        checkbox_filter("Done", False),
        status_filter("Priority", "High")
    ),
    sorts=[sort_by_property("Due Date", "ascending")]
)
for page in results:
    title = page["properties"]["Name"]["title"][0]["plain_text"]
    print(f"- {title}")
```

## Available Scripts

| Script              | Purpose                                       |
| ------------------- | --------------------------------------------- |
| `notion_wrapper.py` | Client setup, token validation, retry wrapper |
| `create_page.py`    | Create pages, property builders               |
| `add_blocks.py`     | Append blocks, block type builders            |
| `query_database.py` | Query, filter, sort, search                   |

## References

- [Property Types](./references/property-types.md) - All 24 property types with examples
- [Block Types](./references/block-types.md) - All block types with structures
- [Rich Text](./references/rich-text.md) - Formatting, links, mentions
- [Pagination](./references/pagination.md) - Handling large result sets

## Important Constraints

### Rate Limits

- **3 requests/second** average (burst tolerated briefly)
- Use `api_call_with_retry()` for automatic rate limit handling
- 429 responses include `Retry-After` header

### Authentication Model

- **Page-level sharing** required (not workspace-wide)
- User must explicitly add integration to each page/database:
  - Page → ... menu → Connections → Add connection → Select integration

### API Version (v2.6.0+)

- Uses `data_source_id` instead of `database_id` for multi-source databases
- Legacy `database_id` still works for simple databases
- Scripts handle both patterns automatically

### Operations NOT Supported

- Workspace settings modification
- User permissions management
- Template creation/management
- Billing/subscription access

## API Behavior Patterns

Insights discovered through integration testing (test citations for verification).

### Rate Limiting & Retry Logic

`api_call_with_retry()` handles transient failures automatically:

| Error Type       | Behavior          | Wait Strategy                            |
| ---------------- | ----------------- | ---------------------------------------- |
| 429 Rate Limited | Retries           | Respects Retry-After header (default 1s) |
| 500 Server Error | Retries           | Exponential backoff: 1s, 2s, 4s          |
| Auth/Validation  | Fails immediately | No retry                                 |

_Citation: `test_client.py::TestRetryLogic` (lines 146-193)_

### Read-After-Write Consistency

Newly created blocks may not be immediately queryable. Add 0.5s minimum delay:

```python
append_blocks(client, page_id, blocks)
time.sleep(0.5)  # Eventual consistency delay
children = client.blocks.children.list(page_id)
```

_Citation: `test_integration.py::TestBlockAppend::test_retrieve_appended_blocks` (line 298)_

### v2.6.0 API Migration

| Old Pattern                     | New Pattern (v2.6.0+)              |
| ------------------------------- | ---------------------------------- |
| `client.databases.query()`      | `client.data_sources.query()`      |
| `filter: {"value": "database"}` | `filter: {"value": "data_source"}` |

_Citation: `test_integration.py::TestDatabaseQuery` (line 110)_

### Archive-Only Deletion

Pages cannot be permanently deleted via API - only archived (moved to trash):

```python
client.pages.update(page_id, archived=True)  # Trash, not delete
```

_Citation: `test_integration.py` cleanup fixture (lines 72-76)_

## Edge Cases & Validation

### Property Builder Edge Cases

| Input             | Behavior                      | Valid? |
| ----------------- | ----------------------------- | ------ |
| Empty string `""` | Creates empty content         | Yes    |
| Empty array `[]`  | Clears multi-select/relations | Yes    |
| `None` for number | Clears property value         | Yes    |
| Zero `0`          | Valid number (not falsy)      | Yes    |
| Negative `-42`    | Valid number                  | Yes    |
| Unicode/emoji     | Fully preserved               | Yes    |

_Citation: `test_property_builders.py::TestPropertyBuildersEdgeCases` (lines 302-341)_

### Input Validation Responsibility

Builders are intentionally permissive - validation happens at API level:

| Property | Builder Accepts | API Validates    |
| -------- | --------------- | ---------------- |
| Date     | Any string      | ISO 8601 only    |
| URL      | Any string      | Valid URL format |
| Checkbox | Truthy values   | Boolean expected |

**Best Practice**: Validate in your application before building properties.

_Citation: `test_property_builders.py::TestPropertyBuildersInvalidInputs` (lines 347-376)_

### Token Validation

- Case-sensitive: Only lowercase `ntn_` and `secret_` valid
- Format check happens before API call (saves unnecessary requests)
- Empty/whitespace tokens rejected immediately

_Citation: `test_client.py::TestClientEdgeCases` (lines 196-224)_

## Query & Filter Patterns

### Compound Filter Composition

```python
# Empty compound (matches all)
and_filter()  # {"and": []}

# Deep nesting supported
and_filter(
    or_filter(filter_a, filter_b),
    and_filter(filter_c, filter_d)
)
```

_Citation: `test_filter_builders.py::TestFilterEdgeCases` (lines 323-360)_

### Filter Limitations

Filters don't exclude NULL properties - check in Python:

```python
if row["properties"]["Rating"]["number"] is not None:
    # Process non-null values
```

_Citation: `test_integration.py::TestDatabaseQuery::test_query_database_with_filter` (lines 120-135)_

### Pagination Invariants

| Condition          | `has_more` | `next_cursor`      |
| ------------------ | ---------- | ------------------ |
| More results exist | `True`     | Present, non-None  |
| No more results    | `False`    | May be absent/None |

Always check `has_more` before using `next_cursor`.

_Citation: `test_integration.py::TestDatabaseQuery::test_query_database_with_pagination` (lines 137-151)_

## Error Handling

```python
from notion_client import APIResponseError, APIErrorCode

try:
    result = client.pages.create(...)
except APIResponseError as e:
    if e.code == APIErrorCode.ObjectNotFound:
        print("Page/database not found or not shared with integration")
    elif e.code == APIErrorCode.Unauthorized:
        print("Token invalid or expired")
    elif e.code == APIErrorCode.RateLimited:
        print(f"Rate limited. Retry after {e.additional_data.get('retry_after')}s")
    else:
        raise
```

## Installation

```bash
uv pip install notion-client  # v2.6+ required for data_source support
```

Or use PEP 723 inline dependencies (scripts include them).

---

## Troubleshooting

| Issue                        | Cause                            | Solution                                              |
| ---------------------------- | -------------------------------- | ----------------------------------------------------- |
| Object not found             | Page not shared with integration | Share page: ... menu → Connections → Add integration  |
| Unauthorized                 | Token invalid or expired         | Generate new token at notion.so/my-integrations       |
| Rate limited (429)           | Too many requests                | Use `api_call_with_retry()` for automatic handling    |
| Empty results from query     | Filter matches nothing           | Verify filter syntax and property names               |
| Block not found after create | Eventual consistency delay       | Add 0.5s delay after write before read                |
| Invalid property type        | Wrong builder used               | Check property type in database schema                |
| Token format rejected        | Wrong prefix (case-sensitive)    | Token must start with `ntn_` or `secret_` (lowercase) |
| Data source ID not working   | Old API version                  | Upgrade notion-client to latest version               |


## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set79

The whole set →
doppler-secret-validation The doppler-secret-validation skill helps store secrets in Doppler, verify retrieval, and test API authentication. Use it to check a token before relying on it in a project. CX Codex +1 135installs link-validation link-validation runs an offline lychee pass over a project's markdown and reports broken relative links, root-relative paths and anchors. Handy right before you commit docs. CX Codex +1 135installs session-recovery session-recovery troubleshoots missing Claude Code sessions when claude -r reports no conversations found or files save to incorrect paths. CX Codex +1 135installs session-chronicle session-chronicle connects findings, decisions, and code changes to session UUIDs. Use it when you need to trace where work came from or record session provenance. CX Codex +1 135installs hooks-development The hooks-development skill guides you through building and debugging Claude Code hooks, with a focus on output visibility. Use it when a hook runs but its message never reaches the agent. CX Codex +1 133installs asciinema-cast-format asciinema-cast-format is a Claude Code skill that helps parse NDJSON headers and terminal events in asciinema v3 .cast recordings. CX Codex +1 132installs python-workspace python-workspace converts MQL5 indicators to Python and exports MetaTrader 5 data headlessly with automated correlation checks. CX Codex +1 131installs terminal-print terminal-print turns iTerm2 output or a session file into a PDF, then sends it to a network printer. It also provides an AirPrint workaround for blank pages on listed HP LaserJet Pro models. CX Codex +1 131installs

More in the catalog

Project sponsors

Companies that keep this analytics open