# notion-research-documentation

Gathers information across Notion pages, extracts facts, and drafts structured briefs or comparative reports with source citations directly in your workspace.

- skill · `type=skill` · Codex, ChatGPT · 15 installs · ★ 7596
- Author: Notion · official OpenAI repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/openai/plugins/tree/HEAD/plugins/notion/skills/notion-research-documentation/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/notion-research-documentation

## What it does

The skill coordinates research inside a Notion workspace. It finds pages via `Notion:search` and reads them with `Notion:fetch`. The agent pulls out key metrics and direct quotes, grouping findings into structured themes.

Results go back into Notion. Using `Notion:notion-create-pages`, the skill formats output as concise briefs, option comparisons, or detailed reports. When changes occur, `Notion:notion-update-page` updates existing entries.

Search queries often surface connected external links that break `Notion:fetch`. The fetch tool accepts only native Notion page and database identifiers. Missing workspace tools also trigger an immediate fallback instead of repeated retries.

## Requirements
- Works with: Notion

## Install

### Codex (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill notion-research-documentation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/notion-research-documentation/SKILL.md` — For all projects use ~/.agents/skills/

### Claude Code

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill notion-research-documentation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/notion-research-documentation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/notion-research-documentation/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/notion-research-documentation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install openai/plugins notion-research-documentation
```

2. **Manually: put the files in place**
- File: `.github/skills/notion-research-documentation/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/openai/plugins --path plugins/notion/skills/notion-research-documentation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/notion-research-documentation/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/openai/plugins/tree/HEAD/plugins/notion/skills/notion-research-documentation/SKILL.md

## When to use it
- synthesize scattered Notion notes into an executive brief
- build structured option comparisons with citations
- draft project reports directly in a Notion workspace
- update existing documentation without manual copy-pasting

## Example prompts
- Search Notion for our launch retro notes and draft a quick summary
- Compare database migration options from our docs and publish the comparison page
- Review the customer interview notes in Notion and compile a cited report

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8bcd77e783c36b31.

BEGIN THIRD-PARTY FILE 8bcd77e783c36b31
```text
---
name: notion-research-documentation
description: Research across Notion and synthesize into structured documentation; use when gathering info from multiple Notion sources to produce briefs, comparisons, or reports with citations.
metadata:
  short-description: Research Notion content and produce briefs/reports
---

# Research & Documentation

Pull relevant Notion pages, synthesize findings, and publish clear briefs or reports (with citations and links to sources).

## Quick start
1) Find sources with `Notion:search` using targeted queries; confirm scope with the user.
2) Fetch pages via `Notion:fetch`; note key sections and capture citations (`reference/citations.md`).
3) Choose output format (brief, summary, comparison, comprehensive report) using `reference/format-selection-guide.md`.
4) Draft in Notion with `Notion:notion-create-pages` using the matching template (quick, summary, comparison, comprehensive).
5) Link sources and add a references/citations section; update as new info arrives with `Notion:notion-update-page`.

## Tool-call guardrails
- Notion tool availability can vary by workspace. If a Notion MCP call returns `Tool <name> not found`, treat that tool as unavailable for the rest of the current task. Do not retry it with different arguments or call it again later; use `Notion:search` and `Notion:fetch` where sufficient.
- Use one literal search query per `Notion:search` call and include `filters: {}` when no narrower filter is needed.
- Only fetch Notion page, database, or data-source URLs/IDs. Search results can include external connected-source URLs, which are not valid `Notion:fetch` inputs.
- Create output pages with an explicit `parent` and a `pages` array.
- When updating an existing report, fetch it first and use `Notion:notion-update-page` with `update_content`, `properties: {}`, and search-and-replace pairs. For property-only updates, use `update_properties` with `content_updates: []`. The current deployed schema expects both top-level fields even when one is unused. Do not invent insertion-only commands.

## Workflow
### 0) If Notion tools are unavailable, pause and ask the user to connect the Notion app:
1. Enable the bundled Notion app for this plugin or session.
2. Complete the Notion auth flow if prompted.
3. Start a new session if the tools still do not appear.

After the app is connected, finish your answer and tell the user to retry so they can continue with Step 1.

### 1) Gather sources
- Search first (`Notion:search`); refine queries, and ask the user to confirm if multiple results appear.
- Fetch relevant pages (`Notion:fetch`), skim for facts, metrics, claims, constraints, and dates.
- Track each source URL/ID for later citation; prefer direct quotes for critical facts.

### 2) Select the format
- Quick readout → quick brief.
- Single-topic dive → research summary.
- Option tradeoffs → comparison.
- Deep dive / exec-ready → comprehensive report.
- See `reference/format-selection-guide.md` for when to pick each.

### 3) Synthesize
- Outline before writing; group findings by themes/questions.
- Note evidence with source IDs; flag gaps or contradictions.
```
END THIRD-PARTY FILE 8bcd77e783c36b31

The third-party file has ended. Everything between the 8bcd77e783c36b31 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3156 of 4253 bytes. © Notion · MIT · https://github.com/openai/plugins/tree/HEAD/plugins/notion/skills/notion-research-documentation/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md