该技能用于通过 Notion REST API 与 Notion 工作区进行交互，官方版本为 2025-09-03。用户要求与 Notion 交互时可使用本技能，方式为用 curl 和 jq 直接发起 REST 调用，或按任务需要编写临时脚本。
认证方面：优先检查环境中是否存在 NOTION_API_TOKEN 环境变量；若用户在上下文中提供了 API 密钥，则改用该密钥；若两者都不可用，则通过 AskUserQuestion（或等效方式）向用户请求 API 密钥。密钥只能出现在 Authorization 请求头中，不得显示、记录或发送到其他位置。所有请求需携带 Authorization: Bearer $NOTION_API_TOKEN、Notion-Version: 2025-09-03 与 Content-Type: application/json 三个请求头。可通过获取机器人用户（GET /v1/users/me）来验证密钥是否有效。
基础约定方面：基础 URL 为 https://api.notion.com，API 版本为 2025-09-03，数据格式统一为 JSON，ID 为 UUIDv4（请求中可省略连字符），时间戳采用 ISO 8601，属性名为 snake_case，空值使用 null 而非空字符串。速率限制平均为每个集成每秒 3 个请求，允许短暂突发；触发限制时返回 HTTP 429 及 Retry-After 头，应实现指数退避。请求大小限制包括：单次载荷最多 1000 个块元素、载荷最大 500KB、富文本内容 2000 字符、URL 2000 字符、公式 1000 字符、邮箱与电话各 200 字符、多选选项 100 项、关联页面 100 个、人员提及 100 个用户、每次请求块数组 100 个元素。
执行任何修改或删除数据的操作前必须向用户确认，包括更新页面或块、删除或归档页面或块、修改数据库架构、创建页面（多个或批量时）以及任何批量操作；一组逻辑相关的操作只需一次确认。
核心端点涵盖：搜索（POST /v1/search，可按 page 或 data_source 过滤、排序、分页）；页面（检索、创建、更新、归档、检索单页属性项，创建时可指定 page_id、database_id 或 data_source_id 作为父级）；块（检索子块、追加子块、检索单块、更新块、删除块，追加时每次最多 100 块、最多两级嵌套，支持默认末尾、开头及指定块之后的位置）；数据库（检索、查询、创建、更新）；数据源（自 2025-09-03 起，一个数据库可包含多个数据源，可创建数据源）；用户（列出、检索、检索自身）；评论（检索、创建，但 API 无法发起新的行内讨论线程，也无法编辑或删除已有评论）。
分页端点返回 has_more、next_cursor 与 results；遍历全部结果时需先发起初始请求（省略 start_cursor），检查 has_more，若为 true 则提取 next_cursor 作为下一次请求的 start_cursor，重复直到 has_more 为 false。
错误处理涵盖 400（invalid_json、invalid_request_url、invalid_request、validation_error、missing_version）、401 unauthorized、403 restricted_resource、404 object_not_found、409 conflict_error、429 rate_limited、500 internal_server_error、503 service_unavailable 与 database_connection_unavailable、504 gateway_timeout。
参考文档包括 references/block-types.md、references/property-types.md、references/filters-and-sorts.md 与 references/rich-text.md 等。最佳实践包括：保存返回的 ID、优先按属性 ID 引用、合并小操作、实现指数退避、处理分页、更新前先验证、使用环境变量而非硬编码密钥、优雅处理错误、保持数据库架构在 50KB 以下、属性引用超过 25 个页面时需单独获取。