AGENT SKILL

notion

Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls.

License 许可
AGPL-3.0
最近更新
2026-09-07
Stars
★ 1
Forks
0

01 前言 Front Matter

name
notion
homepage
https://developers.notion.com/cli/get-started/overview
description
Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls.

03 SKILL.md 正文

Notion

Prefer official ntn CLI. Use curl only when ntn is unavailable or a raw request is clearer.

Setup

npm install -g ntn
ntn --version
ntn login

Script/headless auth:

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

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:

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

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

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

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

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

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.

PilotDeck Migration Note

  • Source: /var/folders/27/xyyzc_n172l3jjmnxgqmhhzh0000gn/T/tmp.AyWDWGKoS4/openclaw/skills/notion
  • Review status: candidate for PilotDeck native skills pack.
  • Platform-specific OpenClaw/Hermes metadata was removed or should be ignored during review.

04 同仓库更多 Skills

rufeng0411
rufeng0411/Nova-Ai-Studio

wireframe-mobile-flow

A lo-fi multi-screen MOBILE flow wireframe — three or four phone frames laid out in a row on a board, showing a connected user flow (Onboarding → Home feed → Item detail → Confirm). Grey-box content inside each device, dashed connector arrows + numbered step labels between screens, and a couple of annotation callouts. Reads like an app flow pinned to a whiteboard before any pixels are committed. Use when the brief asks for "mobile wireframe", "app flow", "user flow wireframe", "lo-fi mobile", "low fidelity", "线框图", "移动端线框", or "App 流程".

★ 1
rufeng0411
rufeng0411/Nova-Ai-Studio

web-prototype

General-purpose desktop web prototype. Single self-contained HTML file built by copying the seed `assets/template.html` and pasting section layouts from `references/layouts.md`. Default for any landing / marketing / docs / SaaS page when no more specific skill matches.

★ 1
rufeng0411
rufeng0411/Nova-Ai-Studio

waitlist-page

Minimal pre-launch landing with email capture, brand logo, and optional decorative layer. Reads DESIGN.md for colors, typography, and layout rules. Best for: product launches, beta signups, early access programs, indie projects.

★ 1
rufeng0411
rufeng0411/Nova-Ai-Studio

team-okrs

OKR tracker page — quarter banner, three objectives with their key results as progress bars, owner avatars, status pills, and a "this quarter at a glance" sidebar. Use when the brief mentions "OKRs", "key results", "objectives", or "目标".

★ 1
rufeng0411
rufeng0411/Nova-Ai-Studio

pricing-page

A standalone pricing page — header, plan tiers, feature comparison table, and an FAQ. Use when the brief asks for "pricing", "plans", "subscription tiers", or a "compare plans" page.

★ 1
rufeng0411
rufeng0411/Nova-Ai-Studio

pm-spec

Product spec / PRD as a single page — problem, success metrics, scope, user stories, design notes, rollout plan, open questions. Use when the brief mentions "PRD", "spec", "product spec", "feature brief", or "需求文档".

★ 1