notion-skill

name	notion-skill
version	1.0.0
description	Work with Notion pages and databases via the official Notion API. Create, read, and update pages and database entries.
author	G-HunterAi
license	MIT
tags	["notion","workspace","docs","databases","wiki"]
platforms	["all"]
category	integration
emoji	📝
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 Skill

Work with Notion pages and databases using the official Notion API. Create, read, update, and manage workspace content.

When to Use

• Managing Notion pages and databases
• Syncing data to/from Notion
• Wiki and knowledge base management
• Workspace documentation updates
• Database queries and filtering
• Bulk page operations

When NOT to Use

• Task management (use mission-control skill)
• Document creation from scratch (use doc-converter skill)
• Presentation building (use remotion skill)
• File hosting (use native cloud storage)

Prerequisites

1. Notion Account — Free or paid subscription
2. Internal Integration — Create at https://www.notion.so/my-integrations
3. Notion API Key — Get the Internal Integration Token
4. Local CLI Tool — Install one of:
   • Node.js: npm install -g notion-cli
   • Python: pip install notion-cli-py

Setup Steps

1. Create a Notion Integration at https://www.notion.so/my-integrations
2. Copy the Internal Integration Token
3. Export as environment variable:

   export NOTION_API_KEY=secret_xxx
   

4. Share the integration with the pages/databases you want to access
5. Install local CLI tool (Node.js or Python)
6. Verify setup: notion-cli --version

Note: Unshared content is invisible to the API. Grant explicit access to each page/database.

Profiles (personal / work)

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

Default profile: personal

Override via:

export NOTION_PROFILE=work

Pages

Read page:

notion-cli page get <page_id>

Append blocks:

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

Prefer appending over rewriting content.

Create page:

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

Databases

Inspect schema:

notion-cli db get <database_id>

Query database:

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

Create row:

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

Update row:

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:

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

Error Handling

Error	Cause	Recovery
401	Invalid or missing API key	Verify NOTION_API_KEY is set correctly
403	Integration not shared with page	Share integration: Page settings → Connections → Add integration
404	Page/database doesn't exist	Check page ID and confirm it exists
429	Rate limited	Wait 60 seconds; Notion limits ~3 req/sec
500	Notion server error	Retry with exponential backoff

Works Well With

• mission-control — Manage tasks linked to Notion pages
• agent-memory — Store agent context in Notion databases
• workflow-orchestrator — Automated Notion workflows

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
• Always request confirmation before schema changes
• Test queries against non-production databases first

Pitfalls

• Document failure modes as you encounter them