前言¶
很多团队把需求、竞品笔记、技术方案、会议纪要都堆在 Notion 里。信息确实在，但要用的时候往往得自己翻十几页、对照几份笔记，再手工整理成简报或对比表。来回切换、漏引用来源、结论对不上原始页面，是知识工作里很常见的摩擦。
Agent Skill 格式（SKILL.md）把可复用的工作流打包成文件夹，Agent 按描述自动或按指令加载。OpenAI 在公开目录 openai/skills 的 .curated 分类里提供了 notion-research-documentation：在已连接 Notion MCP 的前提下，跨页面检索、综合证据，并写成带引用的简报、摘要、对比或完整报告。本文按官方 SKILL.md 与相关说明，介绍它是什么、怎么装、怎么用。
这是什么¶
notion-research-documentation 的官方描述是：在 Notion 中跨页面做调研，并把结果综合成结构化文档；适用于需要从多个 Notion 来源整理简报、对比分析或报告，且要求带来源引用的场景。
- 归属：收录在 openai/skills 仓库的
skills/.curated/notion-research-documentation（curated 技能，可按名称安装）。Notion 侧也有同名工作流出现在 makenotion/claude-code-notion-plugin 中，核心步骤一致：搜索 → 拉取 → 综合 → 新建页面。 - 解决什么问题：把「分散在多页的事实、指标、主张」收成一份可读文档，正文内联引用，文末集中 Sources，必要时给出建议与后续动作。
- 依赖：它不是单独爬 Notion 网页，而是通过 Notion MCP 暴露的工具（如
Notion:notion-search、Notion:notion-fetch、Notion:notion-create-pages、Notion:notion-update-page）读写工作区。未连接 MCP 时，官方流程要求先暂停并完成接入。
说明：openai/skills 仓库 README 已标注该仓库 deprecated，后续 Codex 技能/插件示例以 openai/plugins 与官方 Build plugins 文档为准；下文安装命令仍以该 curated 目录当前公开的 $skill-installer 用法为准。
核心功能与亮点¶
结合官方 SKILL.md、reference/ 与 examples/，能力可以概括为下面几块。
-
先搜后读，再确认范围
用Notion:notion-search做定向检索；结果较多时与用户确认范围。再用Notion:notion-fetch读全文，摘取事实、日期、指标、约束，并记录页面 URL/ID 供引用。 -
按目标选输出体裁
reference/format-selection-guide.md给出决策树与篇幅参考：
- 多方案权衡 → Comparison（约 800–1200 词）
- 时效性强、话题简单 → Quick Brief（约 200–400 词）
- 正式/战略级长文 → Comprehensive Report（约 1500+ 词）
- 其余默认 → Research Summary（约 500–1000 词）
对应模板在reference/下（如quick-brief-template.md、research-summary-template.md、comparison-template.md、comprehensive-report-template.md）。 -
综合时强调证据与缺口
先列提纲，按主题/问题归类；关键事实优先保留直接摘录并绑定来源；标出信息缺口或互相矛盾之处，始终对齐用户目标（决策、摘要、计划或建议）。 -
写回 Notion，并带引用
用Notion:notion-create-pages按模板创建页面，通常包含标题、摘要、关键发现、支撑证据、建议/下一步；正文内联引用，文末 References/Sources。后续可用Notion:notion-update-page追加变更说明。 -
附带可复用参考与示例
-reference/：高级搜索、格式选择、各模板、引用规范等
-examples/：竞品分析、技术排查、市场调研、行程规划等端到端演示
安装与启用¶
这类 Skill 遵循通用 Agent Skills 约定，可在支持该标准的工具中使用。不同工具的安装目录和启用方式不同，下面只写已核实的做法。
1. 先接通 Notion MCP¶
官方 Skill 写明：若 MCP 调用失败，先完成 Notion MCP 接入。Codex 示例为：
codex mcp add notion --url https://mcp.notion.com/mcp
然后启用远程 MCP 客户端（二选一）：在 config.toml 中设置 [features].rmcp_client = true，或运行：
codex --enable rmcp_client
再登录 OAuth：
codex mcp login notion
登录成功后需要重启 Codex，再继续调研流程。Notion 官方也说明 MCP 可对接 Cursor、Claude Code、Codex 等 MCP 客户端，服务端点为 https://mcp.notion.com/mcp（推荐 Streamable HTTP）。在 Cursor 等工具里按各自 MCP 设置添加同一 URL 并完成授权即可；未授权时搜索/读写都会失败。
2. 在 Codex 中安装该 Skill¶
curated 技能可在 Codex 会话里用内置 $skill-installer 按名称安装（默认对应 skills/.curated）：
$skill-installer notion-research-documentation
也可按目录 URL 安装：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/notion-research-documentation
安装后重启 Codex。官方文档说明：CLI/IDE 中可用 /skills 或 $ 显式点名技能；描述匹配时也可由 Agent 隐式选用。
3. 在 Cursor 中放置 Skill¶
Cursor 会从项目或用户目录加载 Skills，例如：
| 位置 | 范围 |
|---|---|
.cursor/skills/ 或 .agents/skills/ |
项目级 |
~/.cursor/skills/ 或 ~/.agents/skills/ |
用户级 |
兼容加载 .claude/skills/、.codex/skills/ 及对应用户目录。将本 Skill 文件夹（至少含 SKILL.md，建议连同 reference/、examples/）放到上述某一路径，例如：
.cursor/skills/notion-research-documentation/SKILL.md
在 Agent 对话里用 / 搜索技能名显式调用，或在任务描述匹配 description 时由 Agent 自动选用。也可在 Customize → Skills 查看已发现技能。从 GitHub 导入时，可按 Cursor 文档通过 Remote Rule (Github) 等方式引入仓库内容。
4. 在 Claude Code 等工具中¶
若使用 Notion 官方插件仓库中的同名 Skill，按该插件的安装说明启用即可；工作流仍依赖 Notion MCP 的 search/fetch/create 一类工具。未在官方材料中写明的路径与命令，这里不臆造。
典型用法示例¶
官方 Quick start 可概括为五步：
Notion:notion-search检索，并与用户确认范围Notion:notion-fetch拉取页面，按reference/citations.md记录引用- 按
format-selection-guide.md选定 brief / summary / comparison / comprehensive - 用对应模板起草，经
Notion:notion-create-pages写入 Notion - 补全 Sources；有更新时用
Notion:notion-update-page
examples/competitor-analysis.md 演示了「调研竞品定价并做对比文档」：
用户意图示例：
Research competitor pricing models and create a comparison document
检索示意（官方示例中的调用形态）：
Notion:notion-search
query: "competitor pricing"
query_type: "internal"
filters: {
created_date_range: {
start_date: "2024-01-01"
}
}
随后对命中页面逐个 Notion:notion-fetch，再 Notion:notion-create-pages 生成对比页（含 Executive Summary、对比矩阵、分竞品分析、建议与 Sources）。技术排查、市场调研、行程规划等见同目录其他示例。
在 Codex 中也可显式点名，例如：
$notion-research-documentation 根据 Notion 里最近的技术方案页，写一份研究摘要并带回链引用
在 Cursor 中则可用 /notion-research-documentation（以实际发现的技能名为准）配合同类自然语言需求。
适用场景与注意事项¶
适合：
- 产品/策略：竞品对比、选项权衡、决策简报
- 工程：跨多页技术方案的排查纪要或调查摘要
- 知识管理：把散落笔记收成带引用的研究报告或高管可读长文
- 需要「结论可回溯到原页面」的协作场景
注意：
- 必须先有 Notion MCP 且账号有权限；搜不到或打不开页面时，先检查连接、团队空间与页面权限（Notion 侧同名 Skill 也提示过这类问题）。
- 输出质量受工作区内容限制：Skill 综合的是你能访问到的 Notion 内容，不会凭空补全未写入的事实。
- 注意时效：官方建议核对页面 last-edited；过时信息应在文中标明。
- 多结果时先确认范围，避免把不相关页面写进同一份报告。
- 仓库迁移：若你主要跟 Codex 插件生态，留意
openai/skills的 deprecation 说明，以当前官方 plugins / skills 文档为准核对安装入口。
小结¶
notion-research-documentation 把「Notion 多页检索 → 证据综合 → 按模板成文 → 带回链写回」收成一套可复用 Agent 工作流。对已经把知识沉淀在 Notion 里的团队，它减少的是手工翻页与整理，而不是替代你对结论负责。接好 Notion MCP，装好 Skill，从一次具体的对比或摘要任务试起即可。
官方目录：
https://github.com/openai/skills/tree/main/skills/.curated/notion-research-documentation
