home / skills / openclaw / skills / notion-skill

notion-skill skill

safe

This skill helps you manage Notion pages and databases via the official API, using a safe CLI workflow for read, create, update, and query tasks.

npx playbooks add skill openclaw/skills --skill notion-skill

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.2 KB

---
name: notion
description: Work with Notion pages and databases via the official Notion API.
homepage: https://developers.notion.com
metadata:
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - NOTION_API_KEY
    install:
      - id: node
        kind: note
        label: "Requires notion-cli (Node.js) or notion-cli-py (Python). See docs below."
---

# Notion

This skill lets the agent work with **Notion pages and databases** using the official Notion API.

The skill is declarative: it documents **safe, recommended operations** and assumes a local CLI
(`notion-cli`) that actually performs API calls.

## Authentication

- Create a Notion Integration at https://www.notion.so/my-integrations
- Copy the Internal Integration Token.
- Export it as:

```bash
export NOTION_API_KEY=secret_xxx
```

Share the integration with the pages or databases you want to access.
Unshared content is invisible to the API.

## Profiles (personal / work)

You may define multiple profiles (e.g. personal, work) via env or config.

Default profile: personal

Override via:

```bash
export NOTION_PROFILE=work
```

## Pages

**Read page:**

```bash
notion-cli page get <page_id>
```

**Append blocks:**

```bash
notion-cli block append <page_id> --markdown "..."
```

Prefer appending over rewriting content.

**Create page:**

```bash
notion-cli page create --parent <page_id> --title "..."
```

## Databases

**Inspect schema:**

```bash
notion-cli db get <database_id>
```

**Query database:**

```bash
notion-cli db query <database_id> --filter <json> --sort <json>
```

**Create row:**

```bash
notion-cli page create --database <database_id> --props <json>
```

**Update row:**

```bash
notion-cli page update <page_id> --props <json>
```

## Schema changes (advanced)

Always inspect diffs before applying schema changes.

Never modify database schema without explicit confirmation.

Recommended flow:

```bash
notion-cli db schema diff <database_id> --desired <json>
notion-cli db schema apply <database_id> --desired <json>
```

## Safety notes

- Notion API is rate-limited; batch carefully.
- Prefer append and updates over destructive operations.
- IDs are opaque; store them explicitly, do not infer from URLs.

Overview

This skill lets the agent work with Notion pages and databases via the official Notion API. It provides safe, recommended operations for reading, creating, appending, querying, and updating content while assuming a local CLI tool performs the actual API calls. The design emphasizes non-destructive workflows and explicit confirmation for schema changes.

How this skill works

The skill issues declarative commands to a local CLI (notion-cli) which performs authenticated Notion API requests using an Integration token. It exposes actions for reading pages, appending blocks, creating pages or database rows, querying databases, inspecting schema diffs, and applying schema updates. Rate limits and opaque ID handling are respected to minimize accidental data loss.

When to use it

Automate reading or exporting Notion page content
Append notes or logs to an existing page without overwriting
Create or update database rows from external systems or scripts
Inspect and query database schemas and rows before integrations
Apply schema changes only after reviewing diffs and getting confirmation

Best practices

Store and export the Notion Integration token via environment variables (NOTION_API_KEY) and isolate profiles via NOTION_PROFILE
Prefer append and incremental updates over rewriting entire pages or deleting content
Always inspect database schema and diffs before applying changes; require explicit confirmation for schema modifications
Batch requests thoughtfully to respect Notion API rate limits
Treat Notion IDs as opaque values; persist them explicitly rather than deriving from URLs

Example use cases

Append a daily summary to a team notes page without altering existing content
Create a new database row when a support ticket is received and update it as the issue progresses
Query a project database with filters and sorts to generate a status report
Inspect database schema diffs and apply controlled changes during a migration
Maintain separate personal and work profiles to manage credentials and access boundaries

FAQ

How do I authenticate the skill?

Create a Notion Integration, copy the Internal Integration Token, and export it as NOTION_API_KEY in your environment. Share the integration with pages or databases you need to access.

Can I modify database schema automatically?

Schema changes are supported but should be done cautiously: inspect diffs first and require explicit confirmation before applying to avoid breaking existing data.