Preface

Many teams pile requirements, competitor notes, technical plans, and meeting minutes into Notion. The information is indeed there, but when you need to use it, you often have to flip through dozens of pages, cross-reference several notes, and manually organize them into a briefing or comparison table. Switching back and forth, missing citation sources, and conclusions that do not match the original pages are very common frictions in knowledge work.

The Agent Skill format (SKILL.md) packages reusable workflows into folders, which Agents can load automatically or on command. OpenAI provides notion-research-documentation in the .curated category of the public directory openai/skills: on the premise that Notion MCP is connected, it can search across pages, synthesize evidence, and write briefings, summaries, comparisons or full reports with citations. This article introduces what it is, how to install it, and how to use it, based on the official SKILL.md and related instructions.

What It Is

The official description of notion-research-documentation is: conduct research across pages in Notion and synthesize the results into structured documents. It is suitable for scenarios where you need to organize briefings, comparative analyses or reports from multiple Notion sources and require source citations.

  • 归属: It is included in skills/.curated/notion-research-documentation of the openai/skills repository (curated skills, which can be installed by name). There is also a workflow with the same name on the Notion side in makenotion/claude-code-notion-plugin, and the core steps are consistent: Search → Pull → Synthesize → Create New Page.
  • What Problem It Solves: It collects “facts, indicators, and claims scattered across multiple pages” into a readable document, with inline citations in the body and a centralized Sources section at the end, and provides suggestions and follow-up actions when necessary.
  • Dependencies: It does not crawl Notion web pages separately, but reads and writes the workspace through tools exposed by Notion MCP, such as Notion:notion-search, Notion:notion-fetch, Notion:notion-create-pages, and Notion:notion-update-page. If MCP is not connected, the official process requires pausing first and completing the connection.

Note: The README of the openai/skills repository has marked this repository as deprecated. Subsequent Codex skills/plugin examples shall be subject to openai/plugins and the official Build plugins documentation; the installation commands below are still based on the current public $skill-installer usage in that curated directory.

Core Features and Highlights

Combined with the official SKILL.md, reference/ and examples/, the capabilities can be summarized into the following sections.

  1. Search first, read later, and confirm the scope
    Use Notion:notion-search for targeted retrieval; if there are many results, confirm the scope with the user. Then use Notion:notion-fetch to read the full text, extract facts, dates, indicators, and constraints, and record the page URL/ID for citation.

  2. Choose output format according to goals
    reference/format-selection-guide.md provides a decision tree and word count reference:
    - Trade-offs between multiple solutions → Comparison (about 800–1200 words)
    - Strong timeliness, simple topic → Quick Brief (about 200–400 words)
    - Formal/strategic long article → Comprehensive Report (about 1500+ words)
    - Others default to → Research Summary (about 500–1000 words)
    Corresponding templates are in reference/ (such as quick-brief-template.md, research-summary-template.md, comparison-template.md, comprehensive-report-template.md).

  3. Emphasize evidence and gaps during synthesis
    First outline the structure and categorize by topic/problem; prioritize retaining direct excerpts of key facts and binding their sources; mark information gaps or contradictions, and always align with user goals (decision-making, summary, planning or suggestions).

  4. Write back to Notion with citations
    Use Notion:notion-create-pages to create pages according to the template, which usually includes title, summary, key findings, supporting evidence, suggestions/next steps; inline citations in the body and References/Sources at the end. You can use Notion:notion-update-page to add change descriptions later.

  5. Include reusable references and examples
    - reference/: Advanced search, format selection, various templates, citation specifications, etc.
    - examples/: End-to-end demonstrations such as competitor analysis, technical troubleshooting, market research, itinerary planning, etc.

Installation and Activation

This type of Skill follows the general Agent Skills convention and can be used in tools that support this standard. The installation directory and activation method vary depending on the tool. Below are only the verified practices.

1. Connect Notion MCP first

The official Skill states: If the MCP call fails, complete the Notion MCP connection first. The Codex example is:

codex mcp add notion --url https://mcp.notion.com/mcp

Then enable the remote MCP client (choose one of the two): set [features].rmcp_client = true in config.toml, or run:

codex --enable rmcp_client

Then log in via OAuth:

codex mcp login notion

After successful login, you need to restart Codex before continuing the research workflow. Notion official also states that MCP can be connected to MCP clients such as Cursor, Claude Code, and Codex, and the service endpoint is https://mcp.notion.com/mcp (Streamable HTTP is recommended). In tools such as Cursor, you can add the same URL according to their respective MCP settings and complete the authorization; search/read/write operations will fail if not authorized.

2. Install this Skill in Codex

Curated skills can be installed by name using the built-in $skill-installer in a Codex session (the default corresponds to skills/.curated):

$skill-installer notion-research-documentation

You can also install by directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/notion-research-documentation

Restart Codex after installation. The official documentation states that you can explicitly name skills with /skills or $ in the CLI/IDE; they can also be implicitly selected by the Agent when the description matches.

3. Place the Skill in Cursor

Cursor loads Skills from the project or user directory, for example:

Location Scope
.cursor/skills/ or .agents/skills/ Project-level
~/.cursor/skills/ or ~/.agents/skills/ User-level

It is compatible with loading .claude/skills/, .codex/skills/ and their corresponding user directories. Place this Skill folder (at least containing SKILL.md, it is recommended to include reference/ and examples/ together) into one of the above paths, for example:

.cursor/skills/notion-research-documentation/SKILL.md

You can search for the skill name with / in the Agent conversation to call it explicitly, or the Agent will automatically select it when the task description matches the description. You can also view discovered skills in Customize → Skills. When importing from GitHub, you can introduce the repository content through methods such as Remote Rule (Github) according to the Cursor documentation.

4. In tools such as Claude Code

If you use the Skill with the same name in the official Notion plugin repository, enable it according to the installation instructions of the plugin; the workflow still relies on tools such as search/fetch/create of Notion MCP. Paths and commands not specified in official materials will not be fabricated here.

Typical Usage Examples

The official Quick start can be summarized into five steps:

  1. Notion:notion-search for retrieval, and confirm the scope with the user
  2. Notion:notion-fetch to pull pages and record citations according to reference/citations.md
  3. Select brief / summary / comparison / comprehensive format according to format-selection-guide.md
  4. Draft using the corresponding template, and write to Notion via Notion:notion-create-pages
  5. Complete the Sources section; use Notion:notion-update-page for updates

examples/competitor-analysis.md demonstrates “researching competitor pricing models and creating a comparison document”:

Example user intent:

Research competitor pricing models and create a comparison document

Retrieval illustration (call form in the official example):

Notion:notion-search
query: "competitor pricing"
query_type: "internal"
filters: {
  created_date_range: {
    start_date: "2024-01-01"
  }
}

Then call Notion:notion-fetch for each hit page, and then call Notion:notion-create-pages to generate a comparison page (including Executive Summary, comparison matrix, competitor-by-competitor analysis, suggestions and Sources). See other examples in the same directory for technical troubleshooting, market research, itinerary planning, etc.

You can also explicitly name it in Codex, for example:

$notion-research-documentation 根据 Notion 里最近的技术方案页，写一份研究摘要并带回链引用

In Cursor, you can use /notion-research-documentation (subject to the actual discovered skill name) with similar natural language requirements.

Applicable Scenarios and Notes

Applicable to:

  • Product/strategy: Competitor comparison, option trade-offs, decision briefings
  • Engineering: Troubleshooting minutes or investigation summaries across multiple technical solution pages
  • Knowledge management: Organize scattered notes into cited research reports or long articles readable by executives
  • Collaboration scenarios where “conclusions can be traced back to the original pages” are required

Notes:

  1. Must have Notion MCP connected and account permissions first; if you cannot find or open pages, check the connection, team space, and page permissions first (the official Notion Skill also reminded about this issue).
  2. Output quality is limited by workspace content: The Skill synthesizes only the Notion content you can access, and will not make up unwritten facts out of thin air.
  3. Pay attention to timeliness: The official recommends checking the last-edited time of the page; outdated information should be marked in the text.
  4. Confirm the scope first when there are multiple results, to avoid including irrelevant pages in the same report.
  5. Repository migration: If you mainly follow the Codex plugin ecosystem, pay attention to the deprecation notice of openai/skills, and check the installation entry based on the current official plugins/skills documentation.

Summary

notion-research-documentation packages the reusable Agent workflow of “Notion multi-page search → evidence synthesis → template-based writing → write back with inline citations”. For teams that have deposited their knowledge in Notion, it reduces the manual flipping and organizing work, rather than replacing your responsibility for the conclusions. Just connect Notion MCP, install the Skill, and try a specific comparison or summary task first.

Official directory:
https://github.com/openai/skills/tree/main/skills/.curated/notion-research-documentation