New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Notion

by magnus919 in magnus919/agent-skills

Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and…

MITAuto-check passedKnowledge Management

Install Notion

skills CLI
$ npx skills add magnus919/agent-skills --skill notion -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install magnus919/agent-skills notion --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/magnus919/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/notion .claude/skills/notion && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
notion
GitHub stars
115
Token cost
~2.2k tokens
SKILL.md length
968 words
Files
7 (incl. scripts, references)
Skills in repo
131
Repo updated
First seen
Licence
MIT

At a glance

Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and…

  • Works in 5 steps: Read-only discovery before any mutation.… → Confirm the target, scope, and rollback… → Respect bounded reads. Notion paginates… → …
  • An agent needs to read Notion content
  • SKILL.md covers Operating contract, The notion-cli script, Operating loop and Pages, databases, search, plus 6 more sections
  • Runs Python scripts from its folder; needs NOTION_TOKEN

What it does

Notion is an agent skill from magnus919/agent-skills. Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation. Use when an agent needs to read Notion content, answer questions from a team wiki or database, or make a confirmed edit. Do not use for building Notion integrations or block-level page composition beyond property updates (that is Notion API application…

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including scripts and reference files (for example `README.md`, `evals/evals.json` and `references/00-source-index.md`). Compatibility notes: The bundled notion-cli script runs on Python 3.9+ with only the standard library. --help and page/database/search reads need no network; live reads require a…

It sits in Knowledge Management, covering Knowledge bases. It works with Notion. The repository describes itself as: Curated collection of AI agent skills for Hermes and other agent frameworks. The licence is MIT.

When your agent uses it

  • An agent needs to read Notion content
  • Answer questions from a team wiki
  • Make a confirmed edit
  • Building Notion integrations

Example prompts

  • “/notion”

Requirements

  • Python 3
  • A credential in NOTION_TOKEN
  • Compatibility (from SKILL.md): The bundled notion-cli script runs on Python 3.9+ with only the standard library. --help and page/database/search reads need no network; live reads require a Notion integration token (secret_...) with the right workspace capabilities and network access to api.notion.com.

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Read-only discovery before any mutation. Retrieve pages, query databases, and search freely. The bundled notion-cli script makes reads…
  2. Confirm the target, scope, and rollback path before acting. Creating a page or updating properties changes a shared workspace that…
  3. Respect bounded reads. Notion paginates with page_size and has_more; never page past what the task needs. notion-cli --limit caps every…
  4. Keep evidence bounded. Quote short page titles, property values, and IDs; never paste full pages, tokens, or raw API payloads into chat.
  5. Know the API version. The Notion-Version header pins the API contract; reads that work today can change with a version bump. notion-cli…

What it can do on your machine

Read from SKILL.md and the folder at commit 22b4723. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • NOTION_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    The bundled notion-cli script runs on Python 3.9+ with only the standard library. --help and page/database/search reads need no network; live reads require a Notion integration token (secret_...) with the right workspace capabilities and network access to api.notion.com.

    From compatibility in the SKILL.md frontmatter.

Context cost

Notion loads about 2.2k tokens when it runs, and up to ~3.9k if it reads all its reference files. Until then it costs about 149 tokens; SKILL.md has 968 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~149
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from magnus919/agent-skills at commit 22b4723, republished under its MIT licence (© magnus919). 968 words, ~2,234 tokens.

Download SKILL.mdSave it as .claude/skills/notion/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
name
notion
description
Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation. Use when an agent needs to read Notion content, answer questions from a team wiki or database, or make a confirmed edit. Do not use for building Notion integrations or block-level page composition beyond property updates (that is Notion API application development), or for other knowledge bases (that is their own tooling).
compatibility
The bundled notion-cli script runs on Python 3.9+ with only the standard library. --help and page/database/search reads need no network; live reads require a Notion integration token (secret_...) with the right workspace capabilities and network access to api.notion.com.
license
MIT
metadata.source
https://developers.notion.com/reference
metadata.source_index
references/00-source-index.md
metadata.research_checked
2026-08-03

Notion Operations

Use this skill to read and, with explicit confirmation, write Notion content through the Notion API: pages, database queries, search, and page property updates. This is a tool skill for the Notion platform. Building Notion integrations, writing complex block compositions, or building an app on the Notion API is application development; this skill owns the everyday agent workflow: finding the right page, answering from a database, and making a confirmed edit.

Operating contract

  1. Read-only discovery before any mutation. Retrieve pages, query databases, and search freely. The bundled notion-cli script makes reads without writing anything.
  2. Confirm the target, scope, and rollback path before acting. Creating a page or updating properties changes a shared workspace that teammates read. Both require an explicit human directive plus --dry-run preview and --yes confirmation through notion-cli. Property updates overwrite existing values — state the current value and the replacement before confirming.
  3. Respect bounded reads. Notion paginates with page_size and has_more; never page past what the task needs. notion-cli --limit caps every search and query.
  4. Keep evidence bounded. Quote short page titles, property values, and IDs; never paste full pages, tokens, or raw API payloads into chat.
  5. Know the API version. The Notion-Version header pins the API contract; reads that work today can change with a version bump. notion-cli sends 2022-06-28 by default and honors NOTION_VERSION.

The notion-cli script

scripts/notion-cli is an agent-first, stdlib-only CLI over the Notion API. It covers the full issue scope: pages, databases (query), search, and updates.

bash
notion/scripts/notion-cli --help                           # no token or network needed
notion/scripts/notion-cli --json pages get --page-id <page>
# Read only properties you plan to change; absent names are marked explicitly
notion/scripts/notion-cli --json pages get --page-id <page> --property Status --property Reviewer
notion/scripts/notion-cli --json --limit 10 databases query --database-id <db>
notion/scripts/notion-cli --json search query --query "on-call runbook"
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --dry-run
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --yes
notion/scripts/notion-cli pages create --parent-database <db> --title "New row" --yes

Exit codes: 0 success, 1 API error or failed check, 2 usage error. Creates and updates are guarded: without --dry-run or --yes the script refuses with exit 1 and never calls the API. Reads are bounded by --limit (default 20, max 100).

Operating loop

  1. Locate the content: search query to find pages and databases by text, or a known ID directly.
  2. Read with bounds: pages get for a single page, databases query for rows in a database (optionally with a JSON --filter), always capped by --limit.
  3. Triage the answer: map the question to evidence (page title + properties, database rows, search results with has_more state).
  4. Act with confirmation: only a human directive to change, previewed with --dry-run and confirmed with --yes.
  5. Verify: re-read the page (pages get) and confirm the property values landed.
  • Pages (GET /pages/{id}): a page is an ID, a title (extracted from the title or Name property), a URL, timestamps, and typed property summaries. JSON output includes each property's type, value, and completeness; --property NAME may be repeated to select properties and marks a requested absent property as present: false. Human output marks incomplete properties as <incomplete: reason>. Long text also includes a truncation marker and original character count, so it cannot be mistaken for a verified full value.
  • Databases (POST /databases/{id}/query): query rows as pages with a page_size cap and an optional structured --filter JSON file (e.g. {"property": "Status", "select": {"equals": "Done"}}). has_more tells you whether the cap hid further rows.
  • Search (POST /search): finds pages and databases by text across the integration's accessible workspace; results are bounded by --limit.
  • Updates (PATCH /pages/{id}): property updates overwrite values (select, status, checkbox, rich text, etc.). Preview the exact properties payload with --dry-run and confirm with --yes; verify with a follow-up pages get.
Show full SKILL.md (417 more words)Show less

Integration access model

  • Notion integrations authenticate with a bot-style token (secret_...) and can only see the pages and databases explicitly shared with the integration. A page that exists in the workspace but is not shared returns 404/object_not_found — that is an access-model result, not a missing page.
  • The Notion-Version header selects the API contract. The CLI defaults to 2022-06-28; set NOTION_VERSION when a workspace or application pins a different version.
  • Tokens are workspace-scoped credentials. Store them in the environment (NOTION_TOKEN), never in code, chat, or commits. Revoke a leaked integration token in the Notion integration settings.

Reference routing

Load whenReference
Sources, version notes, refresh procedurereferences/00-source-index.md
API endpoints, pagination, property types, filters, and error handlingreferences/01-api-operations.md

Included artifacts

  • scripts/notion-cli: bounded, stdlib-only CLI (pages get/create/update, databases query, search; --json; --limit; mutations gated by --dry-run/--yes).
  • tests/test_notion_cli.py: 21 deterministic tests against a stub Notion API, including typed property read-back, explicit absent/truncated states, pagination failures, the mutation gate, and the read-only contract.
  • references/: dated source index + API operations reference.
  • evals/evals.json: six output-quality evaluation cases for agent runs.

Verification boundary

ClaimMinimum evidence
A page exists and its titlenotion-cli pages get --page-id ... --json returns the title and ID
A database query answered the questionnotion-cli databases query --json returns bounded rows with has_more state
Search found the contentnotion-cli search query --json returns the matching page/database with ID and title
An update landednotion-cli pages update --yes exits 0 and a follow-up pages get --property NAME shows each changed property's typed value; compare it with the requested value
A mutation is safe to runnotion-cli ... --dry-run prints the exact payload that would be sent

Hard boundaries

  • Never create or update a page without a human directive, --dry-run preview, and --yes confirmation — Notion edits are visible to everyone with access to the page.
  • Never claim a page is missing when it may simply not be shared with the integration; verify the access model first.
  • Never page reads past --limit; never dump full pages, tokens, or raw payloads into chat.
  • This skill operates the Notion API. It does not build Notion integrations (application development) or cover other knowledge-base products.

When not to use

  • Building Notion integrations or apps (OAuth flows, custom blocks, public API products, block-tree composition beyond property updates) — that is application development; see backend-engineering for service design.
  • Other knowledge bases and document tools (Confluence, Google Docs, wikis) — each has its own tooling; this skill covers Notion only.
  • Workspace administration (user management, workspace settings, integration approval) — that is the Notion admin console.

© magnus919, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references) in notion of magnus919/agent-skills.

  • SKILL.md
  • README.md
  • evals/evals.json
  • references/00-source-index.md
  • references/01-api-operations.md
  • scripts/notion-cli
  • tests/test_notion_cli.py

Open the folder on GitHubat commit 22b4723

Compare with similar skills

Notion next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Notion compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Notion this skillmagnus919/agent-skills115—~2.2kAutomated safety check: PassMIT
Enterprise SearchZhixiangLuo/10xProductivity479—~535Automated safety check: PassMIT
Knowledge Base From Vaultskrun-dev/skrun210—~1.4kAutomated safety check: PassMIT
Kb Refreshtechwolf-ai/ai-first-toolkit132—~1.3kAutomated safety check: PassMIT
Knowledge Searchdataelement/bisheng12k—~1.1kAutomated safety check: PassApache-2.0
Capture Conversationoutline/outline41k—~474Automated safety check: PassCustom licence

Similar skills

  • Enterprise Search

    ZhixiangLuo/10xProductivity

    Search your entire company's institutional knowledge in one query — Slack, Confluence, Jira, Linear, Notion, GitHub, plus any AI or multi-source search tool listed in verifiedconnections.md.

    479 GitHub stars~535 tokensUpdated 3 mo ago
    Knowledge ManagementAuto-check passed

  • Knowledge Base From Vault

    skrun-dev/skrun

    Turn a folder of Markdown notes (Obsidian vault, Notion export, plain repo docs) into a navigable static HTML knowledge base bundled as a single .zip file.

    210 GitHub stars~1.4k tokensUpdated 18 days ago
    Knowledge ManagementAuto-check passed

  • Kb Refresh

    techwolf-ai/ai-first-toolkit

    Add new sources to your knowledge base or re-scrape existing ones to pick up changes.

    132 GitHub stars~1.3k tokensUpdated 11 days ago
    Knowledge ManagementAuto-check passed

  • Knowledge Search

    dataelement/bisheng

    Search the user's knowledge bases and knowledge spaces (企业知识库检索).

    12k GitHub stars~1.1k tokensUpdated today
    Knowledge ManagementAuto-check passed

  • Capture Conversation

    outline/outline

    Save the current conversation, a decision, or a set of notes as a document in an Outline collection; use when the user wants to keep what was discussed in their knowledge base.

    41k GitHub stars~474 tokensUpdated yesterday
    Knowledge ManagementAuto-check passed

  • Find And Cite

    outline/outline

    Answer questions from the Outline knowledge base with quotes and links to the source documents; use when the user asks what the team knows, documented, or decided about a topic.

    41k GitHub stars~537 tokensUpdated yesterday
    Knowledge ManagementAuto-check passed

More from magnus919/agent-skills

All 131 skills in this repo

  • Artifact Pyramids

    magnus919/agent-skills

    Organize durable agent research outputs as summaries, analysis, and evidence dossiers.

    115 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

  • Ascii City Engine

    magnus919/agent-skills

    Build portable, first-person colored ASCII city engines and small GIS-derived city packs.

    115 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Color Management

    magnus919/agent-skills

    Manage color workflows with ICC profiles, working spaces, gamut mapping, and color science.

    115 GitHub stars~2.6k tokensUpdated today
    Auto-check: notes

  • Data Scientist

    magnus919/agent-skills

    A skill your agent uses for PhD-level expertise in data science, statistics, and machine learning: rigorous statistical analysis, experimental design, causal inference, advanced modeling, research…

    115 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • Docker Compose

    magnus919/agent-skills

    Use Docker Compose to define, run, debug, and harden multi-container applications.

    115 GitHub stars~2k tokensUpdated today
    Auto-check: notes

  • Fpga Development

    magnus919/agent-skills

    Design, review, simulate, and verify FPGA logic using explicit RTL contracts, clock and reset models, CDC analysis, timing constraints, and reproducible implementation evidence.

    115 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Notion

What does Notion do?

Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and…. Notion is an agent skill from magnus919/agent-skills. Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation.

When should I use Notion?

Notion fits situations like: an agent needs to read Notion content; answer questions from a team wiki; make a confirmed edit; building Notion integrations.

How do I install Notion in Claude Code?

Run `npx skills add magnus919/agent-skills --skill notion -a claude-code`. Or copy the skill folder (notion in magnus919/agent-skills) into .claude/skills/notion in your project. Claude Code loads it when a task matches its description.

How do I install Notion in Codex?

Run `npx skills add magnus919/agent-skills --skill notion -a codex`. Or copy the skill folder (notion in magnus919/agent-skills) into .agents/skills/notion in your project. Codex loads it when a task matches its description.

Can I use Notion in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add magnus919/agent-skills --skill notion -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/notion, .gemini/skills/notion, .github/skills/notion and .opencode/skills/notion in your project.

What does Notion need to run?

Going by SKILL.md and its folder, Notion needs Python for the scripts in its folder and credentials named NOTION_TOKEN. Our summary lists: Python 3; A credential in NOTION_TOKEN. Compatibility (from SKILL.md): The bundled notion-cli script runs on Python 3.9+ with only the standard library. --help and page/database/search reads need no network; live reads require a Notion integration token (secret_...) with the right workspace capabilities and network access to api.notion.com..

Does Notion access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Notion safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Notion use?

Notion is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Notion use?

About 2.2k tokens (SKILL.md is roughly 8.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.6k tokens, read only when the agent opens those files.

What are the alternatives to Notion?

Skills that share tags, products or a category with Notion: Enterprise Search (ZhixiangLuo/10xProductivity, 479 stars), Knowledge Base From Vault (skrun-dev/skrun, 210 stars), Kb Refresh (techwolf-ai/ai-first-toolkit, 132 stars) and Knowledge Search (dataelement/bisheng, 12k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Notion?

magnus919 (a GitHub user) maintains it in magnus919/agent-skills, which has 115 GitHub stars. The repository holds 131 skills in this directory. The repository was last updated on October 10, 2026.

Source: magnus919/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.