Use this Skill when an answer is spread across project notes, evaluations and old decisions. Define the judgment you need to make, then find and read the relevant pages. The result should organize evidence around that question and let readers return to the underlying material.
Install and prepare
This guide covers the standalone Skill retained in openai/skills. That repository is deprecated and current examples have moved to openai/plugins; the instructions here describe the linked standalone version, not the latest plugin.
Enter this line in the Codex conversation, not a terminal. If the installed Skill does not appear, restart Codex.
$skill-installer notion-research-documentation
- Local Codex with an available Notion MCP connection
- A Notion workspace authorized through OAuth
- Access and editing permission for the destination page or database
If no connection exists, add the following to ~/.codex/config.toml, then run codex mcp login notion in the terminal and complete OAuth. Current Notion documentation does not require the old Skill’s rmcp_client flag. Reuse an existing working connection instead of configuring it twice. [4]
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
Try a first task
Replace the destination Notion links, then start with:
$notion-research-documentation
Research the Notion material about migrating our support knowledge base. Scope: [project page URL] and linked records. Compare options A and B on cost, migration risk and maintenance. List the proposed sources first. Create a short comparison with page links beside important claims. Separate missing or conflicting evidence; do not invent numbers.
Work through the task
-
Bound the research. Specify the period, project entry page and decision. Resolve similarly named results before treating them as part of the same project.
-
Synthesize around questions. Read key pages, then organize costs, constraints and differences. Preserve dates and distinguish source statements from inference.
-
Choose a readable format. Use a brief, comparison or longer report as appropriate. Place citations near conclusions and identify remaining evidence gaps.
Make the report answer a decision question
Say what the reader will decide, then limit the project, time period and source space. For example: “Compare last quarter’s two customer-onboarding flows in a one-page brief for operations. Use original product and support records, label their dates, and keep conflicting evidence separate.” After searching, the agent should list candidate pages so you can resolve similarly named projects, old revisions and permission-limited pages before synthesis.
A practical output groups material as “question → evidence → possible interpretation → missing information.” Keep metrics with different dates or definitions apart. A meeting opinion is an opinion, not measured performance. Place citations near the claim they support so the reader can return to the source page without guessing from a bibliography.
Check whether the report can be used
The first paragraph should make clear which project and period the conclusion applies to. Spot-check two or three central claims: each link should point to a page actually read, with dates consistent with the report. For missing access, unsupported statements or contradictory records, keep a gap and next question rather than filling it with plausible-sounding facts.
Another case: comparing policy versions
If refund rules are scattered across product and support spaces, ask: “Compare the currently applicable refund guidance in both spaces. List effective dates, affected users and contradictions line by line. Base conclusions only on pages actually read, and flag gaps needing legal confirmation.” Keep current rules, old rules and observed practice separate; a newer page title alone does not establish that a policy is in force. For acceptance, follow one important difference back to its source page and verify date and wording. If the effective date is missing, leave an open question rather than announcing company policy.
Check the result
Readers should be able to move from a recommendation to its supporting page without rereading every source. Spot-check numbers and consequential claims against the originals. A bibliography alone is insufficient if readers cannot tell which source supports which conclusion.
Common blockers
Search returns too many pages. Narrow by project, date and decision. Start with a small relevant set and expand only to fill gaps.
Numbers disagree. Compare definitions and dates; present unresolved differences instead of silently choosing one.
The report feels like pasted summaries. Organize headings around the reader’s questions and explain how each piece of evidence affects the choice.
When a format reference file is missing
Choose the report format from the reader’s decision: comparing options, tracing facts, or making a recommendation. If an example asks for reference/formats.md and that file is missing, inspect the installed format-selection-guide.md and relevant *-format.md files instead of inventing a template or leaving the report blank.