Notion

Notion

Default path is the official Notion MCP connector — covers ~95% of intents (pages, databases, views, comments, search, blocks, users, teams). The ntn CLI is optional and used only for the five cases listed under [Routing](#routing--mcp-vs-cli) below. The skill routes the user's intent to the right transport, runs the [Pre-flight](#pre-flight-do-once-per-session-before-any-content-write) before the first content write, and applies the [Gotchas](#gotchas-empirical--not-in-tool-descriptions-or-ntn---help) — empirical facts not surfaced by tool descriptions or --help.

Pre-flight (do once per session before any content write)

MCP path only — on the ntn CLI branch, skip this and validate shapes against the REST API responses instead.

1. Read the MCP resource notion://docs/enhanced-markdown-spec — the canonical reference for Notion-flavored Markdown used by notion-create-pages content and notion-update-page update_content / replace_content. Don't guess Markdown syntax — Notion's flavor diverges from CommonMark in non-obvious ways.
2. For database row CRUD — notion-fetch the target data source first. The fetch returns the current SQLite-style schema. Property names are case-sensitive; expanded keys apply (date::start | :end | :is_datetime, place::name | address | latitude | longitude | google_place_id, checkbox __YES__ / __NO__, properties literally named id or url → prefix userDefined:).

Routing — MCP vs CLI

Default — MCP

For ~95% of Notion intents. The MCP wraps the API in DSLs that have no CLI equivalent:

• SQL DDL for schemas — notion-create-database / notion-update-data-source
• View DSL — notion-create-view / notion-update-view
• Block-level comments — selection_with_ellipsis against rendered Markdown
• Batch up to 100 rows in one notion-create-pages call
• Semantic search across connected sources (Slack, GDrive, GitHub, Jira, MS Teams, Sharepoint, OneDrive, Linear)

Use the ntn CLI when (and only when):

• File upload to Notion — ntn files create. The MCP has no upload tool.
• Notion Workers / serverless — ntn workers …. The MCP has no Workers tools.
• Headless / CI / non-interactive — NOTION_API_TOKEN=… plus --json and --yes. The MCP requires an interactive Claude session.
• Raw API discovery — ntn api ls enumerates every endpoint. Useful when an action isn't covered by any high-level MCP tool.
• Shell piping — ntn pages get --json | jq … for ad-hoc data wrangling.

If none of the five apply: stay on the MCP. No Notion MCP tools in the session (non-Claude harness, or the connector disabled) — the ntn CLI is your path for every intent above.

When the CLI path is required but ntn is missing

Print the install + auth URLs from [References](#references) and stop. Never auto-install on the user's behalf — auth setup needs an interactive token decision.

References

Defer to these — do not embed their content in the skill body. Each is the single source of truth and stays current without any skill update.

| What | Where | |---|---| | MCP overview + setup (start here for newcomers) | https://developers.notion.com/guides/mcp/overview | | MCP capability evolution (monthly cadence) | https://developers.notion.com/page/changelog | | MCP tool DSL syntax (per tool) | The tool's own description in the active session — read it before first use | | Notion-flavored Markdown spec | MCP resource notion://docs/enhanced-markdown-spec | | ntn CLI installation | https://developers.notion.com/cli/get-started/installation | | ntn CLI authentication (OAuth + NOTION_API_TOKEN) | https://developers.notion.com/cli/get-started/authentication | | ntn CLI command reference | https://developers.notion.com/cli/reference/commands · ntn --help | | Notion REST API reference | https://developers.notion.com/reference |

Gotchas (empirical — not in tool descriptions or ntn --help)

These five facts are stable, repeatedly observed in production sessions, and not surfaced by any tool description or CLI help text. They earn their place in the skill body — everything else defers.

1. selection_with_ellipsis matches rendered Markdown verbatim. Copy the snippet from a fresh notion-fetch. Never paraphrase — Notion's validator rejects on first-character mismatch and the failure mode is silent.
2. New databases land at the bottom of the parent page's children. To reposition: a two-op notion-update-page update_content call — prepend ` at the anchor block, then remove the original. Keep at least one reference present in the page so the child-deletion validator doesn't trip, or pass allowdeletingcontent: true` explicitly.
3. notion-create-pages batches up to 100 rows in a single call. Prefer the batch over a per-row loop — Notion rate-limits aggressively on chatty calls.
4. The MCP shipped 2026-01-15 and gains tools roughly monthly (views 2026-03-11, block-level comments 2026-02-26). Don't trust training-data recall for the current tool set — read the changelog when something looks missing.
5. Writes fail with archived ancestor if any parent (page / database / data source) is in the trash. notion-fetch against the data source still returns the schema, masking this during pre-flight — the failure only surfaces at write time. Before trusting pre-flight to greenlight writes on an unfamiliar target, notion-fetch and check for the deleted attribute on the returned `` tag.

Maintenance

This skill encodes only routing rules, the pre-flight, and the five stable gotchas above. Per-tool syntax → tool descriptions; CLI commands → ntn --help; Markdown rules → the notion://docs/enhanced-markdown-spec resource; capability evolution → https://developers.notion.com/page/changelog; auth → the CLI docs URL. A new MCP tool or ntn subcommand requires no skill update — discovery happens via the tool or CLI itself.

Privacy

Never echo a Notion API token (prefix ntn_… for ntn OAuth or secret_… for integration tokens) in tool output, logs, commits, or PR bodies. The token belongs in .envrc (gitignored, chmod 600) or ~/.config/ntn/, never in tracked files.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: coroboros
• Source: coroboros/agent-skills
• License: MIT
• Homepage: https://coroboros.com

Install and usage instructions live in the source repository linked above.