Notion Agent Skill

Notion

Purpose

Work with the user's Notion workspace: search pages and databases, read page properties, query databases, and write: create pages, append blocks to a page, and update page properties. Use when the user mentions Notion or wants something looked up or recorded in their Notion.

Tooling

All commands go through bin/notion.py:

bin/notion.py auth                              # verify the connection (search with page_size 1)
bin/notion.py search --query "roadmap"           # search pages and databases
bin/notion.py page --id PAGE_ID                  # read a page's properties
bin/notion.py query-db --id DATABASE_ID          # query a database (first 20 rows)

# writes: every one requires the exact --confirm string the CLI prints
bin/notion.py page-create --parent-id PAGE_ID --properties '{"title":{"title":[{"text":{"content":"My note"}}]}}'
bin/notion.py page-create --parent-id DB_ID --parent-type database --properties '{"Name":{"title":[{"text":{"content":"New row"}}]}}'
bin/notion.py block-append --block-id PAGE_ID --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello"}}]}}}]'
bin/notion.py page-update --id PAGE_ID --properties '{"Status":{"status":{"name":"Done"}}}'

IDs are the 32-hex-character Notion IDs (with or without dashes). --properties uses the Notion API property object format (e.g. {"title": {"title": [...]}}), not flattened values.

Auth

• Provider id: notion (credential is collected as custom.notion)
• Collection: Notion internal integration token via the secure credential flow (credentials.request_api_access); create one at notion.so/my-integrations → New integration → copy the "Internal Integration Secret", then share the pages/databases you need with that integration inside Notion
• Required scopes: n/a (integration capabilities are set at notion.so/my-integrations)
• Allowed hosts: api.notion.com
• Status check: bin/notion.py auth (must return "ok": true)

Operating Rules

• Reads need no confirmation. Every write (page-create, block-append, page-update) requires the exact-match --confirm string: run the command once without it, read the refused string from the output, confirm the effect with the user, then re-run with it.
• Notion rate-limits to ~3 requests/second; if a call returns 429, wait the Retry-After seconds and continue.
• Pages and databases must be explicitly shared with the integration inside Notion, or they will not appear in search results and writes to them will fail: if a known page is missing, tell the user to share it with the integration.
• Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/notion.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/notion.py

Maturity

🧪 Draft: written from Notion's public API docs; not yet live-tested end-to-end. The write endpoints (page-create, block-append, page-update) are doc-built only: paths and bodies follow the public docs but have never been run against a real workspace.