Preface

When writing code with AI programming tools like Cursor or Codex, conversations often leave behind quite a lot of “valuable” content: reasons for architecture selection, deployment steps, and pitfalls that are repeatedly asked about. The problem is, this content often stays stuck in the chat window—if you want to find it later, you can only dig through the history; and new team members will have to ask the same questions all over again to get up to speed.

Notion is already the Wiki and documentation hub for many teams. If we could organize the conclusions into structured pages and attach them to the corresponding databases when the conversation ends, knowledge will truly be preserved. notion-knowledge-capture is exactly the Agent Skill built for this purpose: it turns chats and notes into linkable, reusable Notion pages.

What It Is

notion-knowledge-capture comes from OpenAI’s Agent Skills catalog (the .curated curated skills in the openai/skills repository). Its positioning is very clear: it captures conversations and decisions into structured Notion pages, suitable for team Wikis, How-To guides, architecture decision records (ADRs), FAQs, study notes, or official documentation.

It relies on the official Notion-hosted MCP service (https://mcp.notion.com/mcp), using tools like notion-search, notion-fetch, notion-create-pages, and notion-update-page to read and write the workspace. The Skill itself is mainly a SKILL.md with workflows and templates, plus database descriptions in the reference/ folder and examples in the examples/ folder; the Agent will execute the process after reading it.

One thing to note: the openai/skills repository README has indicated that the repository is being deprecated, and for subsequent Codex plugins/skill examples, it is recommended to refer to the OpenAI Plugins documentation; however, the SKILL.md, reference templates, and examples of this Skill can still be obtained in the current directory, and the installation commands in the skills.sh, MCPServers and other directory pages still point to the same path. Just refer to the official SKILL.md as the source of truth.

Core Features and Highlights

Based on the official SKILL.md and supporting files, its capabilities can be summarized as follows.

  1. Six Content Templates
    The reference/ folder contains database descriptions prepared for different use cases, including:

    • team-wiki-database.md: Team Wiki
    • how-to-guide-database.md: Operation Guide
    • faq-database.md: FAQ
    • decision-log-database.md: Decision Log
    • documentation-database.md: Documentation Library
    • learning-database.md: Study/Retrospective Notes

    There is also database-best-practices.md, which covers general conventions for property naming, Owners, Status, Tags, and more.

  2. Fixed Five-Step Workflow
    First clarify “what to capture and who it is for”, then select the right database, extract facts/decisions/steps from the conversation, create or update a page via Notion MCP, and finally link back to the Hub page, add a summary and responsible person. It does not just copy the original chat text into Notion, but structures it by type.

  3. Search First, Then Write to Avoid Duplicate Pages
    The official Quick Start requires first using Notion:notion-search, then Notion:notion-fetch to pull existing pages or database structures, confirm whether to create a new page or update an existing one, and obtain the correct property names and data_source_id.

  4. Discoverability
    After creation, it will also update the Hub page and add relations/backlinks; if there are follow-up tasks, you can create tasks in the relevant task library and link them to each other. The default prompt in agents/openai.yaml also emphasizes capturing decisions, action items, and known owners.

Installation and Activation

This type of Skill is based on the universal SKILL.md format and can be used in tools that support Agent Skills. Please refer to the directory page and repository instructions for the installation method.

Install the Skill

The more common cross-tool installation command (given on the skills.sh / MCPServers directory pages):

npx skills add https://github.com/openai/skills --skill notion-knowledge-capture

In Codex, the repository README states that you can use the built-in $skill-installer to install curated skills by name, for example:

$skill-installer notion-knowledge-capture

After installation, restart the Agent as required by the tool you are using to discover the new Skill. After a successful installation on the Cursor side, the skill directory will generally appear in the project’s .cursor/skills/notion-knowledge-capture (subject to the actual disk location from the CLI).

Connect Notion MCP (Required)

Without Notion MCP, the Skill cannot truly read and write pages. The official SKILL.md steps for Codex are:

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

Enable the remote MCP client (choose one of the following):

# config.toml
[features]
rmcp_client = true

Or:

codex --enable rmcp_client

Then log in via OAuth:

codex mcp login notion

After a successful login, you need to restart Codex before continuing with the capture process.

If you mainly use Cursor, you can follow the official Notion MCP documentation for configuration. An example of the global or project-level .cursor/mcp.json:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Save the file and restart Cursor, complete the OAuth authentication when you first call a Notion tool. For Claude Code, use:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then use /mcp in the session to complete the authorization.

Notion recommends using the hosted MCP (https://mcp.notion.com/mcp), and the open-source local notion-mcp-server is no longer actively maintained.

Typical Usage Examples

The Skill comes with an examples/ folder. Below are condensed official examples of “decision capture” and “How-To” for easy comparison with your own prompts.

1. Turn Architecture Discussions into Decision Records

A user might say:

Write our decision to "migrate the customer API from REST to GraphQL" into the Notion decision library,
adding alternatives, reasons, impact scope, and the responsible person.

The Agent will roughly do the following:
1. Extract Decision / Context / Alternatives / Rationale from the conversation
2. Run Notion:notion-search, for example, query "architecture decisions" or "ADR"
3. Run Notion:notion-fetch to get the database properties (such as Decision, Date, Status, Domain, Impact, etc.)
4. Run Notion:notion-create-pages, specify the correct data_source_id, write the title and properties, and expand the body content in ADR structure
5. Add backlinks from the Architecture Wiki and other Hub pages

The call pattern when creating a page in the official example is similar to:

Notion:notion-create-pages
parent: { data_source_id: "decision-log-collection-id" }
pages: [{
  properties: {
    "Decision": "Migrate to GraphQL API",
    "date:Date:start": "2025-10-16",
    "Status": "Accepted",
    "Domain": "Architecture",
    "Impact": "High"
  },
  content: "(including Context / Decision / Options / Consequences / Plan)"
}]

The actual property names must be based on the schema returned by notion-fetch in your workspace, do not copy the placeholder IDs verbatim.

2. Save Deployment Discussions as a How-To Guide

A user might say:

Save the earlier discussion about production environment releases as a How-To,
include prerequisites, steps, verification checklist, and troubleshooting, and attach it to the Engineering Wiki.

The official example will organize the content as: Overview & Prerequisites → Numbered Steps → Verification → Troubleshooting → Related Docs, then use Notion:notion-update-page to insert the link back into the Wiki index page after creation.

3. Use the Default Intention Directly

The default prompt provided in agents/openai.yaml is:

Capture this conversation into structured Notion pages with decisions,
action items, and owners when known.

It is suitable for one-click knowledge沉淀 after a conversation ends: decisions will go into the decision library, steps will go into How-To guides, and owners should be included as much as possible.

Applicable Scenarios and Notes

Best For:
- Teams already using Notion as their Wiki/ADR/FAQ hub and want to automatically store conclusions from AI programming sessions into the repository
- Teams that need fixed formatting: decisions need to include alternatives, How-To guides need to include prerequisites and troubleshooting
- Teams that collaborate across multiple people and rely on Tags, Owners, Status, and Hub backlinks for discovery and responsibility tracking

Notes for Use:
1. You must connect to Notion MCP first and complete OAuth authentication; permissions are limited to the scope you can access in your Notion workspace.
2. Fetch the schema before writing properties; property names, types, and data_source_id vary by database, hardcoding them will easily lead to failures.
3. Select the correct database when there are multiple candidates; the Skill requires asking the user when uncertain, rather than writing content into a random database.
4. It is suitable for structured knowledge, not for copying entire chat logs verbatim; sensitive information should be desensitized before being stored in the database.
5. Repository Status: When this article was written, the openai/skills README has been marked as deprecated, and long-term maintenance and distribution channels may be migrated; it is recommended to check the official catalog and Notion MCP documentation for updates before installing.

Summary

notion-knowledge-capture connects the “knowledge generated during AI coding chats” to Notion’s structured knowledge base: selecting the right database, extracting structure, creating/updating pages, and linking back to the Hub. For engineering teams already using Notion for team documentation, this is a straightforward “chat → Wiki” workflow.

Official catalog:

https://github.com/openai/skills/tree/main/skills/.curated/notion-knowledge-capture

Notion MCP access guide:

https://developers.notion.com/guides/mcp/get-started-with-mcp