# Implementing Notion Integration for Knowledge Capture in Plugins: A Complete Guide

> Learn to implement Notion integration for knowledge capture in OpenAI plugins. This guide uses `notion-knowledge-capture` to send conversational data to Notion databases.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-02

---

**The OpenAI Plugins repository provides a complete MCP-backed architecture for capturing conversational knowledge directly into structured Notion databases using the `notion-knowledge-capture` skill and template-driven page creation.**

Implementing Notion integration for knowledge capture in plugins requires wiring together MCP tool calls, YAML skill definitions, and database schema templates. The `openai/plugins` repository demonstrates this pattern through a dedicated Notion plugin bundle that transforms chat excerpts, meeting notes, and decisions into structured, linkable Notion pages.

## Understanding the Knowledge Capture Architecture

The Notion plugin bundle centers on a **four-step pipeline** that bridges conversational AI and structured knowledge management. According to the source code in [`plugins/notion/skills/notion-knowledge-capture/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/SKILL.md), the workflow separates policy (guardrails), schema (reference databases), and behavior (skill execution).

### The Four-Step Pipeline

1. **Define what to capture** – The agent extracts purpose, audience, and content type (decision, how-to, FAQ, or wiki) from user input.
2. **Locate the destination database** – Using `Notion:search` and `Notion:fetch`, the skill identifies the target database by matching against reference schemas stored in `plugins/notion/skills/notion-knowledge-capture/reference/`.
3. **Extract and structure** – The agent parses conversation content, extracting facts, actions, rationales, or Q&A pairs for database insertion.
4. **Create or update pages** – The skill calls `Notion:notion-create-pages` (or `Notion:notion-update-page` for edits) using the database's `data_source_id` and populates required properties via markdown templates.

### MCP-Backed Tool Calls

All Notion interactions traverse the Managed Cloud Platform (MCP) layer. The skill exposes four primary tools:

- **`Notion:search`** – Locates databases and existing pages by title or property.
- **`Notion:fetch`** – Retrieves database schemas and page content for inspection.
- **`Notion:notion-create-pages`** – Creates new pages with structured properties and content blocks.
- **`Notion:notion-update-page`** – Modifies existing pages using `command: "update_content"` (see lines 24-25 of [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)).

### Skill Metadata and Guardrails

Each skill file begins with YAML front-matter defining `name`, `description`, and `metadata.short-description`. The knowledge capture skill includes **guardrails** (lines 19-24 of [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)) that enforce early termination if the Notion MCP tools are unavailable, prompting users to connect the Notion app before proceeding.

## Core Components and File Structure

The Notion plugin bundle organizes functionality into distinct files that separate manifest configuration from skill logic:

- **[`plugins/notion/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/notion/.codex-plugin/plugin.json)** – The plugin manifest declaring capabilities and UI metadata.
- **[`plugins/notion/skills/notion-knowledge-capture/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/SKILL.md)** – Primary skill definition containing workflow steps, guardrails, and tool invocation logic.
- **[`plugins/notion/skills/notion-knowledge-capture/reference/team-wiki-database.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/reference/team-wiki-database.md)** – Schema template for wiki entries.
- **[`plugins/notion/skills/notion-knowledge-capture/reference/how-to-guide-database.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/reference/how-to-guide-database.md)** – Schema template for procedural documentation.
- **[`plugins/notion/skills/notion-knowledge-capture/reference/faq-database.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/reference/faq-database.md)** – Schema template for question-answer pairs.
- **[`plugins/notion/skills/notion-knowledge-capture/reference/decision-log-database.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/reference/decision-log-database.md)** – Schema template for decision records.
- **[`plugins/notion/skills/notion-knowledge-capture/examples/decision-capture.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/examples/decision-capture.md)** – End-to-end usage example for decision logging.

## How to Invoke the Notion Knowledge Capture Skill

Developers trigger the knowledge capture workflow through YAML-based skill invocations that specify content type, target audience, and source material.

### Basic Page Creation

To create a new decision log entry from meeting notes, invoke the skill with explicit content type classification:

```yaml
skill: notion-knowledge-capture
input:
  purpose: "Document the Q2 roadmap decision"
  audience: "Product team"
  content_type: "decision"
  conversation: |
    - We decided to postpone Feature X to Q4 because of engineering bandwidth.
    - Alternatives considered: Feature Y (high ROI) and Feature Z (low effort).
    - Final outcome: prioritize Feature Y; revisit Feature X in Q4.

```

The agent executes `Notion:search` to locate the Decision Log database, fetches the schema from [`decision-log-database.md`](https://github.com/openai/plugins/blob/main/decision-log-database.md), maps the conversation bullets to database properties, and calls `Notion:notion-create-pages` with the retrieved `data_source_id`.

### Updating Existing Pages

For modifying existing knowledge pages, pass the `update: true` flag and target URL:

```yaml
skill: notion-knowledge-capture
input:
  update: true
  page_url: "https://www.notion.so/Team-Wiki-12345"
  new_content: |
    Added the latest API version to the integration guide.
    Updated the code snippet to use the new endpoint.

```

The agent calls `Notion:fetch` to retrieve the current page state, computes the content diff, and executes `Notion:notion-update-page` with `command: "update_content"` to apply changes while preserving database relationships.

## Database Templates and Schema Mapping

The reference files in `plugins/notion/skills/notion-knowledge-capture/reference/` define **property maps** and **section skeletons** that ensure created pages conform to target database schemas. Each template specifies:

- **Required properties** – Database columns that must be populated (e.g., "Decision", "Status", "Stakeholders").
- **Markdown templates** – Content blocks injected into the page body.
- **Relation mappings** – Fields linking new pages to existing workspace content for bidirectional traceability.

When the skill creates a page, it injects these templates into the JSON payload for `Notion:notion-create-pages`, ensuring the resulting Notion page matches the team's standardized format for that content type.

## Practical Implementation Example

The following interaction demonstrates the complete workflow when capturing sprint retrospective notes:

```

User: "Can you capture the key takeaways from our sprint retro?"
Assistant: "Sure! What type of page should I create? Options: decision log, FAQ, how-to, or wiki entry."
User: "A wiki entry for the team."
Assistant: "Great. Should I create a new page or update an existing one?"
User: "Create a new page."
Assistant: [Searches Notion for 'Team Wiki' database using Notion:search]
Assistant: [Fetches schema from team-wiki-database.md via Notion:fetch]
Assistant: [Extracts bullet points from retro transcript]
Assistant: [Creates page via Notion:notion-create-pages and links to roadmap]
Assistant: "I've added a new wiki entry titled 'Sprint 42 Retro Highlights' and linked it to the team's roadmap page."

```

This flow leverages the **bidirectional linking** capability mentioned in the source code, where the skill automatically relates new knowledge pages back to originating specs or conversations using Notion relations.

## Summary

- **Implementing Notion integration for knowledge capture in plugins** requires combining MCP tool calls with YAML skill definitions and markdown templates.
- The `notion-knowledge-capture` skill in [`plugins/notion/skills/notion-knowledge-capture/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/SKILL.md) provides a four-step pipeline: define content, locate database, extract structure, and create/update pages.
- **Guardrails** (lines 19-24) enforce tool availability checks before workflow execution.
- **Reference templates** in the `reference/` directory ensure database schema compliance and standardized formatting.
- **Tool calls** (`Notion:search`, `Notion:fetch`, `Notion:notion-create-pages`, `Notion:notion-update-page`) handle all Notion API interactions through the MCP layer.

## Frequently Asked Questions

### What MCP tools does the Notion knowledge capture skill use?

The skill utilizes four primary MCP tools: `Notion:search` for locating databases, `Notion:fetch` for retrieving schemas and page content, `Notion:notion-create-pages` for creating new entries, and `Notion:notion-update-page` for modifying existing content. These tools abstract the direct Notion API, allowing the skill to operate through the Managed Cloud Platform layer.

### How does the skill handle missing Notion connections?

According to the guardrails defined in [`plugins/notion/skills/notion-knowledge-capture/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/notion/skills/notion-knowledge-capture/SKILL.md) (lines 19-24), the skill checks for tool availability before executing the workflow. If the Notion MCP tools are unavailable, the skill aborts early and prompts the user to connect the Notion app, preventing partial execution or errors.

### What content types are supported by the knowledge capture templates?

The reference schemas in `plugins/notion/skills/notion-knowledge-capture/reference/` support four primary content types: **Team Wiki** ([`team-wiki-database.md`](https://github.com/openai/plugins/blob/main/team-wiki-database.md)), **How-To Guides** ([`how-to-guide-database.md`](https://github.com/openai/plugins/blob/main/how-to-guide-database.md)), **FAQ Entries** ([`faq-database.md`](https://github.com/openai/plugins/blob/main/faq-database.md)), and **Decision Logs** ([`decision-log-database.md`](https://github.com/openai/plugins/blob/main/decision-log-database.md)). Each template defines specific required properties and formatting structures appropriate to that content type.

### Can the skill update existing Notion pages?

Yes, by setting `update: true` and providing a `page_url` in the skill input, the agent invokes `Notion:fetch` to retrieve the existing page, computes content differences, and calls `Notion:notion-update-page` with `command: "update_content"`. This preserves existing database relationships while applying new content.