Notion
Drive Notion pages, Markdown content, data sources, comments, and search from the agent via the official ntn CLI with curl fallback.
Overview
Notion is an agent skill for the Build phase that automates Notion pages and API operations through the official ntn CLI.
Install
npx skills add https://github.com/steipete/clawdis --skill notionWhat is this skill?
- Prefers official global ntn CLI; curl only when ntn is missing or raw API is clearer
- Markdown-first page create and update with parent page or data-source parents
- Headless auth via NOTION_API_TOKEN and NOTION_API_VERSION with automatic Authorization headers on ntn api
- Inspect path: ntn doctor, ntn api ls, per-endpoint --help, --spec, and --docs
- OpenClaw metadata documents npm install of ntn and NOTION_API_TOKEN primary env
- Requires ntn or curl binaries per OpenClaw metadata
Adoption & trust: 1.9k installs on skills.sh; 378k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent needs to create or update Notion docs and databases but you only have ad-hoc curl snippets and inconsistent auth.
Who is it for?
Solo builders whose PRDs, tasks, or wikis live in Notion and who want agent-driven doc updates during build and ship.
Skip if: Teams that forbid API tokens in agent environments or want a no-network local-only notes stack.
When should I use this skill?
Agent tasks need Notion page CRUD, Markdown sync, search, or raw v1 API calls with ntn login or NOTION_API_TOKEN.
What do I get? / Deliverables
You run documented ntn commands (or vetted raw API calls) so pages, Markdown content, and searches stay in sync with your repo or agent task.
- Created or updated Notion pages from Markdown
- API-inspected requests via ntn api with correct Notion-Version headers
Recommended Skills
Journey fit
Notion wiring is build-phase integration work when docs and databases are part of the product or ops stack. integrations fits API/CLI skills that connect your agent to external systems of record like Notion workspaces.
How it compares
Task integration skill for Notion’s API—not a replacement for in-app Notion AI or a full PM methodology skill.
Common Questions / FAQ
Who is notion for?
Developers and solo founders using Claude Code, Cursor, or Codex who keep product docs in Notion and want CLI-driven automation.
When should I use notion?
Use it during build integrations when syncing specs or databases, during ship launch prep for changelogs in Notion, or during grow content updates to customer-facing pages.
Is notion safe to install?
It requires network access and a Notion API token; review the Security Audits panel on this Prism page and scope tokens to least-privilege integrations.
SKILL.md
READMESKILL.md - Notion
# Notion Prefer official `ntn` CLI. Use curl only when `ntn` is unavailable or a raw request is clearer. ## Setup ```bash npm install -g ntn ntn --version ntn login ``` Script/headless auth: ```bash export NOTION_API_TOKEN=secret_or_ntn_token export NOTION_API_VERSION=2026-03-11 ``` `ntn api` sets `Authorization` and `Notion-Version` automatically. It uses CLI login by default, or `NOTION_API_TOKEN` when set. ## Inspect ```bash ntn doctor ntn api ls ntn api ls --json ntn api v1/comments --help ntn api v1/comments --spec -X POST ntn api v1/comments --docs -X POST ``` ## Pages Markdown-first helpers: ```bash ntn pages get <page-id> ntn pages get <page-id> --json ntn pages create --parent page:<page-id> --content '# Title\n\nBody' ntn pages create --parent data-source:<data-source-id> < page.md ntn pages update <page-id> --content '# Updated' ntn pages update <page-id> < page.md ntn pages trash <page-id> --yes ``` Notes: - `pages get` prints Markdown with page properties as frontmatter. - Content input: `--content`, stdin, or editor in a TTY. - Parent refs: `page:<id>`, `database:<id>`, `data-source:<id>`. - For properties/templates/full Pages API, use `ntn api v1/pages`. ## Data sources ```bash ntn datasources resolve <database-id> ntn datasources resolve <database-id> --json ntn datasources query <data-source-id> ntn datasources query <data-source-id> --limit 50 --json ntn datasources query <data-source-id> --sort 'Date desc' ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}' ``` Use `resolve` when you have a database ID. Query needs a data source ID. ## Raw API ```bash ntn api v1/users/me ntn api v1/search query=roadmap page_size:=10 ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item' ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \ 'children[0][type]=paragraph' \ 'children[0][paragraph][rich_text][0][text][content]=Hello' ``` Input syntax: - `path=value`: string body field. - `path:=json`: typed JSON body field. - `name==value`: query parameter. - `Header:Value`: request header. - `--data '<json>'` or stdin JSON for larger bodies. - Only one body source per request. ## Files ```bash ntn files create < image.png ntn files create --filename photo.png --content-type image/png < /tmp/photo ntn files create --external-url https://example.com/photo.png ntn files get <upload-id> ntn files list ``` ## Workers ```bash ntn workers new ntn workers deploy ntn workers list --json ntn workers runs list --json ntn workers runs logs <run-id> ``` Workers may require Business/Enterprise plan and workspace enablement. ## Curl fallback ```bash curl -sS "https://api.notion.com/v1/users/me" \ -H "Authorization: Bearer $NOTION_API_TOKEN" \ -H "Notion-Version: 2026-03-11" \ -H "Content-Type: application/json" ``` ## Version notes - Current latest API version: `2026-03-11`. - Use `in_trash`, not `archived`. - Append block positioning uses `position`, not flat `after`. - `transcription` block renamed to `meeting_notes`. - Databases can contain multiple data sources; page parents generally use `data_source_id`.