Skip to main content
skill CX Codex

notion · acedatacloud — Claude Code skill: what it does, how to install

This skill connects Claude Code to Notion’s REST API for workspace search, page editing, database queries, and new page creation.

Apache-2.0 215 installs ★ 17 updated 2026-10-25

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

What notion does

The skill works through curl and jq. It verifies the Notion connection, searches pages and databases, reads page metadata or block content, appends a paragraph, queries database rows, and creates a page under a database. These recipes cover common read and write operations.

Requests require an OAuth bearer token in $NOTION_TOKEN and the Notion-Version: 2022-06-28 header. The integration can access only pages and databases explicitly shared with it. Without $NOTION_TOKEN or permission to the target page, the request will fail.

Large result sets use cursor pagination with next_cursor. Write errors often come from sending a value with the wrong property shape, so the database schema should be read through GET /v1/databases/<id> before building a write request.

What it helps with

  • search a Notion workspace for a page or database
  • read a page and inspect its block content
  • append a paragraph to an existing page
  • filter and sort rows returned from a database
  • create a database page with selected properties

Example prompts for the agent

  • Search Notion for the Q1 budget page and show its content.
  • Append this report to the page with ID PAGE_ID.
  • Query DATABASE_ID for rows where Status is Open, then create a new entry.

How to install notion

1Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill notion -a claude-code

2Manually: put the files in place

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

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

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

Questions about notion

How do I install notion in Claude Code?

Run npx skills add AceDataCloud/Skills --skill notion -a claude-code, then check ~/.claude/skills/notion/SKILL.md.

What does the notion skill do?

It gives Claude Code recipes for the Notion REST API. The skill can search and read pages, append blocks, query databases, and create database pages.

What access does notion need to work with private pages?

Set an OAuth bearer token in $NOTION_TOKEN. The integration can work only with pages and databases that were explicitly shared with it.

Source text

SKILL.md · Apache-2.0
---
name: notion
description: Search, read, append to, and create Notion pages and databases via the Notion REST API. Use when the user mentions Notion, a page in their workspace, or wants to log something to a database.
when_to_use: |
  Trigger when the user wants to read or write something in Notion —
  search a workspace, read a page, append blocks, query a database,
  create a page from a template, etc.
connections: [notion]
allowed_tools: [Bash]
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
---

We drive the [Notion API](https://developers.notion.com/reference) with
`curl + jq`. The user's OAuth bearer token is in `$NOTION_TOKEN`; every
call needs it plus the `Notion-Version` header.

Notion-Version is currently `2022-06-28` (the most recent stable). Bump
this header when Notion ships a new version.

The user's connection only sees the pages and databases they explicitly
shared with the integration when they authorized. If a search or page
read returns nothing, the most likely cause is "the page was never
shared with the integration" — surface that hint to the user.

## Recipes

### Verify auth (always run first)

```sh
curl -sS https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  | jq '{id, name, type, bot: (.bot != null)}'
```

### Search the workspace

```sh
curl -sS https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"query": "Q1 budget", "page_size": 10}' \
  | jq '.results[] | {id, type: .object, url, title: (.properties.title // .properties.Name)?.title?[0]?.plain_text // .child_page?.title}'
```

### Read a page (metadata only)

```sh
curl -sS "https://api.notion.com/v1/pages/PAGE_ID" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28"
```

### Read a page's full content

```sh
curl -sS "https://api.notion.com/v1/blocks/PAGE_ID/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  | jq '.results[] | {type, content: (.[.type] // {})}'
```

### Append a paragraph to a page

```sh
curl -sS -X PATCH "https://api.notion.com/v1/blocks/PAGE_ID/children" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg text "Appended via the assistant." '
    {children: [{
      object: "block",
      type: "paragraph",
      paragraph: {rich_text: [{type:"text", text:{content:$text}}]}
    }]}')"
```

### Query a database

```sh
curl -sS -X POST "https://api.notion.com/v1/databases/DATABASE_ID/query" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Open"}},
    "sorts":  [{"property": "Updated", "direction": "descending"}],
    "page_size": 25
  }'
```

### Create a page in a database

```sh
curl -sS -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc \
        --arg db "DATABASE_ID" \
        --arg title "New entry" \
        '{
          parent: {database_id: $db},
          properties: {
            Name:   {title: [{text: {content: $title}}]},
            Status: {select: {name: "Open"}}
          }
        }')"
```

## Notes

- Notion's pagination is cursor-based: append `start_cursor=$cursor` to
  paginate, using the `next_cursor` from each response. Stop when
  `has_more` is `false`.
- Most write failures (400/404) come from a property type mismatch —
  e.g. sending `{"select": "Open"}` instead of `{"select": {"name": "Open"}}`.
  Read the database schema once via `GET /v1/databases/<id>` if unsure.


## Record the output

After you successfully publish and obtain the live result URL, call the built-in
`publish_artifact` tool ONCE so the user can track this deliverable in **My Outputs**:

```
publish_artifact(kind="document", channel="notion", title="<title>", url="<the REAL returned URL>", status="delivered")
```

Use the real returned URL — never fabricate one. Call it once per published item,
only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
See `_shared/artifacts.md`.

© acedatacloud · Apache-2.0 · AceDataCloud/Skills

Similar skills

All skills for Backend and APIs →

notion by other authors comes first.

notion openclaw This skill connects an agent to Notion through the ntn CLI and API, for reading and editing pages, querying data sources, and uploading files. CX Codex +1 5,700installs notion membrane Connects Notion through the Membrane CLI. The agent queries databases, creates pages and updates blocks without leaving the chat. CX Codex +1 357installs notion imoonkey This skill gives your agent hands-on access to a Notion workspace: find pages, read their content, query databases and write new entries. CX Codex +1 ★ 79repo stars c-notion daxaur c-notion — a skill that hands your agent a set of notion-cli commands for Notion pages, databases and blocks. Useful when edits should happen without opening the browser. CX Codex +1 ★ 179repo stars notion-api intellectronica A skill for interacting with the Notion API through REST requests. Gives agents full access to pages, databases, blocks, and comments — read, create, update, and delete content. CX Codex +1 106,200installs notion-automation claude-office-skills notion-automation automates Notion databases and page templates with cross-platform triggers. Useful for handling leads, task digests, and calendar events. CX Codex +1 5,000installs notion-sdk terrylica notion-sdk — a skill for managing Notion via the official Python SDK. Creates pages and databases, queries information, adds content blocks — all programmatically. CX Codex +1 133installs notion_integration vuralserhat86 The notion_integration skill guides Notion searches, meeting documents, research notes, and spec-to-task workflows. Use it when project knowledge and implementation planning live in a Notion workspace. CX Codex +1 1installs notion-as-code makenotion This skill sets a prerequisite for Notion as Code work in an App: the agent must read the SDK skill before making changes. It also covers troubleshooting. CX Codex +1 ★ 232repo stars

From the same set67

The whole set →

More in the catalog

Project sponsors

Companies that keep this analytics open