agentsclimarketplace
Sign in

Notion

Skill coroboros/agent-skills/skills/notion

Notion access from Claude Code via the official MCP connector (default path, ~95% of intents) or the `ntn` CLI (only for file uploads, Notion Workers, headless/CI scripts, raw API discovery, shell piping). Routes intent to the right transport, pre-flights the Notion-flavored Markdown spec and target data-source schema, and pins the empirical gotchas not surfaced by tool descriptions or `ntn --help`. Use whenever the user wants to read, fetch, search, create, update, query, or organize Notion content — pages, databases, data sources, views, comments, blocks, properties, schemas, wikis, docs — or upload a file to Notion, build a Notion Worker, or script Notion non-interactively. Triggers on Notion, Notion page, Notion database, Notion DB, Notion wiki, Notion doc, Notion comment, Notion view, Notion property, Notion schema, Notion file, Notion Worker, NOTION_API_TOKEN, ntn, ntn api.From its SKILL.md

Install
npx -y skills add coroboros/agent-skills --skill notion

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

5 things to look at

  • skips confirmationTells the agent to proceed without asking first, 1 time: "plus --json and --yes".
  • reads credentialsReads from 1 credential source: `NOTION_API_TOKEN`.
  • 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 6 commands, including `ntn files create` and 5 more.
  • fetches URLsInstructs the agent to fetch 1 URL, including https://developers.notion.com/page/changelog.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

8.0 KB, ~1.5k tokens by cl100k_base, as published. Nobody here has run it

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 below. The skill routes the user's intent to the right transport, runs the Pre-flight before the first content write, and applies the Gotchas — 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:<col>:start | :end | :is_datetime, place:<col>: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 <id> --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 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.

WhatWhere
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 specMCP resource notion://docs/enhanced-markdown-spec
ntn CLI installationhttps://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 referencehttps://developers.notion.com/cli/reference/commands · ntn <command> --help
Notion REST API referencehttps://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 <database url="…" data-source-url="…"> 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 allow_deleting_content: 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 <page_id> and check for the deleted attribute on the returned <page> 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.

What ships with it: 1 file

3.4 KB alongside SKILL.md

evals/

Gives 0 of the 12 instructions most docs writing skills give in ~1.5k tokens

Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06

  • Use third-person for skill descriptionsin 54 of 1951, across 35 files
  • Start descriptions with Use whenin 43 of 1951, across 29 files
  • Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
  • Use active voicein 40 of 1951, across 36 files
  • Map file responsibilities before defining tasksin 36 of 1951, across 29 files
  • Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
  • Ask one question at a timein 35 of 1951
  • Offer execution options after saving the planin 33 of 1951, across 24 files
  • Include complete code in every stepin 33 of 1951, across 27 files
  • Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
  • Announce the skill usage at the startin 30 of 1951
  • Verify agent compliance after adding the skillin 29 of 1951, across 17 files

Said here and by no other author read

  • Use MCP connector for standard Notion tasks
  • Use ntn CLI for file uploads and headless scripts
  • Read enhanced markdown spec before writing content
  • Fetch target data source before database row CRUD
  • Batch up to 100 rows in one create call
  • Check for deleted attribute on parent pages before writing

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.