Notion
This skill lets the agent work with Notion pages and databases using the official Notion API.
The skill is declarative: it documents safe, recommended operations and assumes a local CLI
(notion-cli) that actually performs API calls.
Authentication
- Create a Notion Integration at https://www.notion.so/my-integrations
- Copy the Internal Integration Token.
- Export it as:
export NOTION_API_KEY=secret_xxx
Share the integration with the pages or databases you want to access. Unshared content is invisible to the API.
Profiles (personal / work)
You may define multiple profiles (e.g. personal, work) via env or config.
Default profile: personal
Override via:
export NOTION_PROFILE=work
Pages
Read page:
notion-cli page get <page_id>
Append blocks:
notion-cli block append <page_id> --markdown "..."
Prefer appending over rewriting content.
Create page:
notion-cli page create --parent <page_id> --title "..."
Databases
Inspect schema:
notion-cli db get <database_id>
Query database:
notion-cli db query <database_id> --filter <json> --sort <json>
Create row:
notion-cli page create --database <database_id> --props <json>
Update row:
notion-cli page update <page_id> --props <json>
Schema changes (advanced)
Always inspect diffs before applying schema changes.
Never modify database schema without explicit confirmation.
Recommended flow:
notion-cli db schema diff <database_id> --desired <json>
notion-cli db schema apply <database_id> --desired <json>
Safety notes
- Notion API is rate-limited; batch carefully.
- Prefer append and updates over destructive operations.
- IDs are opaque; store them explicitly, do not infer from URLs.