Use notion-knowledge-capture when a useful discussion would otherwise disappear into chat history. Provide the conversation, the audience and the destination. The Skill selects an appropriate structure and searches existing material first, so the result can connect with the team’s knowledge rather than becoming an isolated duplicate.
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-knowledge-capture
- 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-knowledge-capture
Turn this discussion of refund rules into a Notion decision record. Destination: [paste knowledge-base URL]. First look for an existing record on this topic. Preserve the decision, alternatives, reasoning and open questions. Do not invent owners. Show a page preview and destination before creating or updating it.
Work through the task
-
Choose the document type. A decision needs alternatives and reasoning; a how-to needs prerequisites and steps; an FAQ should follow the reader’s questions.
-
Find the correct destination. Read related pages before choosing an update or a new page. Inspect actual database properties such as title, status, tags and relations before writing.
-
Write and connect it. Include links to the discussion and related policies, then return the resulting page URL. Identify whether owners and deadlines for follow-up work are actually known.
Turn a discussion into reusable knowledge
Supply the discussion link or accessible notes and identify the output as a decision, how-to or FAQ. For a launch retrospective, extract what was decided, why, who owns follow-up and when to revisit it; do not paste a chat transcript into Notion. Ask the agent to search existing pages first. If a same-topic guide exists, propose where to update it. If a new page is needed, inspect the target database’s real title, status, owner and relation properties before writing.
A useful request is: “Turn this payment-webhook debugging discussion into a how-to. First show the related existing pages and target database. Keep only confirmed symptoms, investigation steps and recovery criteria; put unknown causes under open questions. Return the page URL after writing.” The request supplies audience, outcome and evidence boundary, reducing the chance that a provisional theory becomes official policy.
Review the written page
Open the returned Notion page. Check that its title is searchable, a newcomer can follow the steps, and links to the original discussion and related docs work. A decision record should separate the chosen path from alternatives; each FAQ answer should stand alone. If a required database property or permission is missing, retain the prepared content and report the blocker rather than claiming the page was created.
Check the result
Open the page and ask whether a colleague who missed the discussion can understand what was decided, why and what remains uncertain. Check for duplicate documents, broken links and open questions incorrectly presented as settled policy.
Common blockers
A page cannot be found. Open its URL in the same Notion account and check workspace access. Different keywords cannot repair missing authorization.
Database writes fail. Read the destination’s actual properties again instead of assuming another database’s schema applies.
The conversation has no conclusion. Keep a discussion note or open question until you provide the missing decision.
Resolve people properties before writing
When capturing a discussion into a database with Owner or Deciders properties, do not paste symbolic names such as current_user, tech_lead, or eng_team from reference examples as API values. Resolve actual Notion user IDs first; if names are ambiguous, confirm the person before writing. Check the resulting page’s people, decision, and source link.