⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

notion-pro-skill

baixiaodev@baixiaodev⭐ 1 stars· last commit 7mo ago· 0 open issues

name: notion-pro

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 1 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

📝 Notion Pro — Complete Notion API Skill for OpenClaw

The most comprehensive Notion API skill for AI agents.
Built-in Python CLI · Agent operation strategies · Auto-pagination · Recursive blocks · 429 retry

License: MIT Python 3.8+ Notion API ClawHub

English · 中文


Overview

Notion Pro is a production-grade OpenClaw skill that gives AI agents complete control over Notion workspaces. Unlike basic Notion skills that only list API commands, this skill embeds the operational knowledge agents need to work with Notion effectively.

Why Another Notion Skill?

We built this after watching agents fail at Notion tasks in predictable ways:

  • Guessing page IDs instead of searching
  • Missing nested content inside toggles and lists
  • Hitting 429 rate limits and crashing
  • Not knowing that "replace" means delete + append
  • Sending 5000-character strings into a 2000-char field

Notion Pro solves all of these with a combination of smart tooling and embedded strategy.

Feature Comparison

CapabilityNotion ProBuilt-in SkillOther Skills
Agent strategy (5-step workflow)✅❌❌
Recursive block fetch (--recursive)✅❌❌
Auto-pagination (--all)✅❌❌
429 auto-retry (Retry-After)✅❌❌
Positional insert (--after)✅❌❌
Complete API limits reference✅PartialPartial
4 operation pattern SOPs✅❌❌
Zero external dependencies✅N/ANode.js
Bilingual docs (EN + CN)✅EN onlyEN only

Quick Start

Install via ClawHub (Recommended)

npx clawhub@latest install notion-pro

Install Manually

# Clone to your OpenClaw skills directory
git clone https://github.com/baixiaodev/notion-pro-skill.git ~/.openclaw/skills/notion-pro

Configure

  1. Create a Notion Integration and copy the API key
  2. Set up authentication (choose one):
# Option A: Environment variable
export NOTION_API_KEY="ntn_xxxxx"

# Option B: OpenClaw config (openclaw.json)
# Add to skills.entries:
#   "notion-pro": { "apiKey": "ntn_xxxxx" }
  1. Share your pages/databases with the integration in Notion (click "..." → "Connect to" → your integration name)

Verify

python3 ~/.openclaw/skills/notion-pro/scripts/notion_api.py search --query "test"

What's Inside

notion-pro/
├── SKILL.md               # English skill doc (agent-facing)
├── SKILL_CN.md             # 中文技能文档
├── scripts/
│   └── notion_api.py       # Python CLI tool (422 lines, zero deps)
├── README.md               # This file
└── LICENSE                 # MIT

The Python CLI Tool

A single-file Python 3 tool with zero external dependencies (stdlib urllib only). Supports 8 commands:

CommandDescription
searchSearch pages and databases with auto-pagination
get-pageGet page metadata (properties, parent, URL)
get-blocksGet page content with recursive block expansion
query-databaseQuery databases with filters, sorts, auto-pagination
create-pageCreate pages in databases or as sub-pages
update-pageUpdate page properties
append-blocksAppend content blocks with positional insert
delete-blockArchive (soft-delete) a block

Key features:

  • 🔄 429 auto-retry — Reads Retry-After header, retries up to 3 times
  • 📄 Auto-pagination (--all) — Fetches all results across multiple pages
  • 🌳 Recursive blocks (--recursive) — Expands nested blocks up to 5 levels deep
  • 📍 Positional insert (--after) — Insert blocks at specific positions
  • 🔀 API version compatibility — Auto-falls back between /data_sources/ and /databases/ endpoints
  • ⏱️ Rate protection — 350ms delays between paginated/recursive requests

The Agent Strategy

The SKILL.md doesn't just list commands — it teaches agents how to think about Notion tasks:

1. Discover  → search for the target page/database ID
2. Inspect   → read current structure with get-page / get-blocks
3. Plan      → determine operation sequence
4. Execute   → batch operations (≤50 blocks), 300ms intervals
5. Verify    → confirm results with get-blocks

Plus 4 battle-tested operation patterns:

  • Bulk Knowledge Base Population — Schema-first batch writes
  • Page Content Update — Delete + append workflow
  • Recursive Full-Page Read — Nested toggle/list expansion
  • Conditional Query + Bulk Update — Filter, iterate, update

Usage Examples

# Search for a page
python3 scripts/notion_api.py search --query "Meeting Notes" --filter page

# Read full page content (recursive)
python3 scripts/notion_api.py get-blocks --block-id "abc123" --recursive

# Query database with filter
python3 scripts/notion_api.py query-database \
  --database-id "def456" \
  --filter '{"property": "Status", "select": {"equals": "Active"}}' \
  --all

# Create a database entry
python3 scripts/notion_api.py create-page \
  --parent-id "def456" \
  --parent-type database \
  --properties '{"Name": {"title": [{"text": {"content": "New Item"}}]}, "Status": {"select": {"name": "Draft"}}}'

# Append content to a page
python3 scripts/notion_api.py append-blocks \
  --block-id "abc123" \
  --children '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello from the API!"}}]}}]'

API Reference

See the full reference in SKILL.md (English) or SKILL_CN.md (中文), including:

  • Complete block type reference (15+ types with JSON examples)
  • Rich text formatting (bold, italic, code, colors, links, mentions)
  • Property type reference (14 types with write examples)
  • API limits quick reference table
  • API version 2025-09-03 migration notes

Contributing

Issues and PRs are welcome! If you've found a Notion API edge case or have a useful operation pattern to share, please open an issue.

License

MIT


中文说明

概述

Notion Pro 是一个生产级 OpenClaw 技能,让 AI Agent 完整掌控 Notion 工作区。不同于仅列出 API 命令的基础技能,本技能内嵌了 Agent 高效操作 Notion 所需的 操作策略知识。

为什么需要另一个 Notion Skill?

我们在实际使用中观察到 Agent 在 Notion 任务上反复犯同样的错误:

  • 猜测页面 ID 而不是先搜索
  • 遗漏 toggle 和列表中的嵌套内容
  • 触发 429 限速后直接崩溃
  • 不知道"替换"实际上是 删除 + 追加
  • 往 2000 字符的字段里塞 5000 字符

Notion Pro 通过智能工具 + 内嵌策略解决了所有这些问题。

快速开始

通过 ClawHub 安装(推荐)

npx clawhub@latest install notion-pro

手动安装

git clone https://github.com/baixiaodev/notion-pro-skill.git ~/.openclaw/skills/notion-pro

配置

  1. 创建 Notion Integration 并复制 API Key
  2. 设置认证(选其一):
    • 环境变量:export NOTION_API_KEY="ntn_xxxxx"
    • OpenClaw 配置:在 openclaw.json 的 skills.entries 中添加 "notion-pro": { "apiKey": "ntn_xxxxx" }
  3. 在 Notion 中将目标页面/数据库共享给集成(点击 "..." → "Connect to")

验证

python3 ~/.openclaw/skills/notion-pro/scripts/notion_api.py search --query "测试"

核心特性

Python CLI 工具

单文件 Python 3 工具,零外部依赖(仅用标准库 urllib),支持 8 个子命令:

命令功能
search搜索页面和数据库,支持自动翻页
get-page获取页面元数据
get-blocks获取页面内容,支持递归展开嵌套块
query-database查询数据库,支持过滤、排序、自动翻页
create-page在数据库或页面下创建新页面
update-page更新页面属性
append-blocks追加内容块,支持指定位置插入
delete-block归档(软删除)块

Agent 操作策略

SKILL.md 不只列出命令,它教会 Agent 如何思考 Notion 任务:

1. Discover  → 搜索目标页面/数据库 ID
2. Inspect   → 读取当前结构
3. Plan      → 确定操作序列
4. Execute   → 分批执行(≤50块),300ms间隔
5. Verify    → 验证结果

加上

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.9 KBupstream ↗
    name: notion-pro
    description: Complete Notion API skill with Python CLI tool — auto-pagination, recursive blocks, 429 retry, and agent operation strategies.
    version: 1.0.1
    homepage: https://github.com/baixiaodev/notion-pro-skill
    metadata: {"clawdbot":{"emoji":"📝"}}
    env:
      - NOTION_API_KEY: Notion integration API key (or configure in openclaw.json → skills.entries.notion-pro.apiKey)
    ---
    
    # Notion Pro — Complete Notion API Skill for OpenClaw
    
    A production-grade Notion API skill with a built-in Python CLI tool. Unlike basic Notion skills that only provide command syntax, this skill includes **agent operation strategies**, **automatic pagination**, **recursive block fetching**, **429 rate-limit retry**, and comprehensive API reference — everything an AI agent needs to operate Notion effectively.
    
    ## What Makes This Different
    
    | Capability | This Skill | Basic Skills |
    |---|---|---|
    | Agent operation strategy (5-step workflow) | ✅ | ❌ |
    | Recursive block fetching (`--recursive`, 5 levels) | ✅ | ❌ |
    | Auto-pagination (`--all`) | ✅ | ❌ |
    | 429 rate-limit auto-retry (Retry-After) | ✅ | ❌ |
    | Positional insert (`--after`) | ✅ | ❌ |
    | API limits quick reference | ✅ Complete | Partial |
    | 4 operation pattern SOPs | ✅ | ❌ |
    | Zero dependencies (stdlib only) | ✅ Python 3 | Node.js / curl |
    
    ## Setup
    
    1. Create a [Notion Integration](https://www.notion.so/profile/integrations) and copy the API key
    2. Configure the key via **one** of:
       - Environment variable: `export NOTION_API_KEY="ntn_xxxxx"`
       - OpenClaw config: `openclaw.json` → `skills.entries.notion-pro.apiKey`
    3. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)
    4. If a page/database isn't found via search, it likely hasn't been shared with the integration yet
    
    ## Tool: notion_api.py
    
    **All Notion operations must go through this script** — do not use curl directly.
    
    Script path: `scripts/notion_api.py` (relative to this skill's directory)
    
    ```bash
    # The script auto-detects its own location. Usage:
    python3 <SKILL_DIR>/scripts/notion_api.py <command> [options]
    ```
    
    ---
    
    ## Agent Operation Strategy (Must Read)
    
    ### Task Planning Workflow
    
    Follow this sequence for any Notion task:
    
    1. **Discover** — Use `search` to find the target page/database ID
    2. **Inspect** — Use `get-page` or `get-blocks` to understand current structure
    3. **Plan** — Determine the operation sequence (create/update/append/delete)
    4. **Execute** — Execute in batches, ≤50 blocks per batch (safety margin)
    5. **Verify** — After critical operations, use `get-blocks` to verify results
    
    ### Read Strategy
    
    - **Search before read**: Never guess IDs — use `search` to find the exact page/database
    - **Recursively read nested content**: `get-blocks` only returns direct children. If a block has `has_children: true`, **you must call `get-blocks` again with that block's ID** to get nested content. Or use `--recursive` for automatic traversal.
    - **Handle pagination**: If response contains `has_more: true`, make multiple calls. Use `--all` for automatic pagination.
    
    ### Write Strategy
    
    - **Split long text**: A single rich_text element's `text.content` is limited to **2000 characters**. Split longer content into multiple paragraph blocks.
    - **Batch writes**: One `append-blocks` call supports up to **100 block elements**. Split into multiple calls if needed.
    - **Replace = Delete + Append**: Notion API has **no** "replace block content" endpoint. To replace content: `delete-block` old blocks, then `append-blocks` new content at the correct position.
    - **Insert position**: `append-blocks` appends to the end by default. To insert at a specific position, use `--after` with the preceding block's ID.
    
    ### Database Write Strategy
    
    - **Schema-First**: Before creating a page, use `get-page` or `query-database` to inspect the database's property schema. Ensure your properties JSON matches.
    - **Title is required**: Every database has exactly one `title` property — it must be provided when creating a page.
    - **Exact property names**: Property names are case-sensitive and space-sensitive.
    
    ---
    
    ## API Limits Quick Reference
    
    | Limit | Value |
    |---|---|
    | Rate limit | **3 requests/sec** (average), returns 429 when exceeded |
    | Max request payload | **500 KB** |
    | Max blocks per payload | **1000 blocks** |
    | Max array elements (blocks/rich_text) | **100** |
    | rich_text `text.content` | **2000 characters** |
    | rich_text `text.link.url` | **2000 characters** |
    | URL property | **2000 characters** |
    | multi_select options | **100** |
    | relation linked pages | **100** |
    | Database schema recommended size | **≤ 50 KB** |
    | Pagination default/max page_size | **100** |
    
    **429 handling**: When rate-limited, the script automatically reads the `Retry-After` header and retries (up to 3 times). For manual batch operations, add 300–500ms between calls.
    
    ---
    
    ## Command Reference
    
    ### Search
    
    ```bash
    python3 scripts/notion_api.py search --query "keyword"
    python3 scripts/notion_api.py search --query "keyword" --filter page
    python3 scripts/notion_api.py search --query "keyword" --filter database --page-size 20
    
    # Pagination (use next_cursor from previous response)
    python3 scripts/notion_api.py search --query "keyword" --start-cursor "xxx"
    
    # Auto-fetch all results (auto-paginates, may take time for large datasets)
    python3 scripts/notion_api.py search --query "keyword" --all
    ```
    
    ### Read Page
    
    ```bash
    # Get page metadata (properties, parent, URL, etc.)
    python3 scripts/notion_api.py get-page --page-id "xxx-xxx"
    
    # Get page content (blocks) — check has_children for recursive fetching
    python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx"
    
    # Recursively fetch full page (auto-expands all nested blocks, max depth 5)
    python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx" --recursive
    
    # Pagination
    python3 scripts/notion_api.py get-blocks --block-id "xxx-xxx" --start-cursor "xxx"
    ```
    
    ### Query Database
    
    ```bash
    # Get all rows
    python3 scripts/notion_api.py query-database --database-id "xxx"
    
    # With filter
    python3 scripts/notion_api.py query-database \
      --database-id "xxx" \
      --filter '{"property": "Status", "select": {"equals": "Active"}}'
    
    # With sort
    python3 scripts/notion_api.py query-database \
      --database-id "xxx" \
      --sorts '[{"property": "Date", "direction": "descending"}]'
    
    # Compound filter (AND/OR)
    python3 scripts/notion_api.py query-database \
      --database-id "xxx" \
      --filter '{"and": [{"property": "Status", "select": {"equals": "Active"}}, {"property": "Priority", "select": {"equals": "High"}}]}'
    
    # Pagination
    python3 scripts/notion_api.py query-database --database-id "xxx" --start-cursor "xxx"
    
    # Auto-fetch all results
    python3 scripts/notion_api.py query-database --database-id "xxx" --all
    ```
    
    ### Create Page
    
    ```bash
    # Create in database (properties must match schema)
    python3 scripts/notion_api.py create-page \
      --parent-id "database_id" \
      --parent-type database \
      --properties '{"Name": {"title": [{"text": {"content": "New Entry"}}]}}'
    
    # Create sub-page with content
    python3 scripts/notion_api.py create-page \
      --parent-id "page_id" \
      --parent-type page \
      --properties '{"title": {"title": [{"text": {"content": "Sub-page Title"}}]}}' \
      --children '[{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello World"}}]}}]'
    ```
    
    ### Update Page Properties
    
    ```bash
    python3 scripts/notion_api.py update-page \
      --page-id "xxx" \
      --properties '{"Status": {"select": {"name": "Done"}}}'
    ```
    
    ### Append Blocks
    
    ```bash
    # Append to end (default)
    python3 scripts/notion_api.py append-blocks \
      --block-id "page_id" \
      --children '[{"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": "Title"}}]}}, {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Body text"}}]}}]'
    
    # Insert after a specific block
    python3 scripts/notion_api.py append-blocks \
      --block-id "page_id" \
      --after "target_block_id"
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/baixiaodev-notion-pro-skill.md

// REPO STATS

1 stars
0 open issues
Last commit: 7mo ago