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
npx skills add AceDataCloud/Skills --skill notion -a claude-codeWhat 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_IDfor 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-code2Manually: put the files in place
~/.claude/skills/notion/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/notion/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill notion -a codex2Manually: put the files in place
.agents/skills/notion/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill notion -a cursor2Manually: put the files in place
.cursor/skills/notion/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install AceDataCloud/Skills skills/notion2Manually: put the files in place
.github/skills/notion/SKILL.md1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill notion -a gemini-cli2Platform CLI
gemini skills install https://github.com/AceDataCloud/Skills --path skills/notionManually: put the files in place
.devin/skills/notion/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill notion -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.