About

Imported from practicalswan/agent-skills (notion-docs/SKILL.md). Install upstream with npx skills add practicalswan/agent-skills --skill notion-docs. Copyright stays with the author.

Notion Documentation

Name: notion-docs
Author: practicalswan

Tech Stack Target / Version: Notion API current version, Markdown-to-Notion transforms, and local template scripts.

Use this skill when Notion is the system of record for specs, runbooks, project tracking, or knowledge management.

Leverage native parallel subagent dispatch and 200k+ context windows where available.

Current MCP Reality

As of March 2026, Notion documents two supported ways to use its MCP server:

Hosted remote MCP endpoint: https://mcp.notion.com/mcp
Local stdio server package: @notionhq/notion-mcp-server

Hosted mode uses OAuth. Local mode uses an internal integration token. Official docs also list supported tools for searching content, reading pages, comments, users, and working with pages and databases.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

Creating or updating Notion pages
Building project trackers or engineering knowledge bases
Organizing specs, ADRs, and onboarding docs in Notion
Adding review comments or using database-backed workflows

Practical Workflow

Confirm whether the client exposes the hosted Notion MCP server or a local stdio connection.
Read or search existing pages before creating duplicates.
Use databases for tracked work and pages for long-form documents.
Keep properties simple: owner, status, last reviewed, tags.
If MCP is unavailable in the current client, fall back to local content prep using the included script and templates.

Operational Notes

Official Notion guidance currently documents an average rate limit of 20 requests per second for integrations.
Tool names can vary slightly by MCP host, but the supported capabilities are stable: search, fetch page content, create or update pages, create or update databases, manage comments, and read user context.

Documentation Stack Reference

Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on Notion conversion and workspace behavior instead of restating the full stack.

Anti-Patterns

Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

Verification Protocol

Before claiming "skill applied successfully":

Pass/fail: The Notion Docs output identifies audience, purpose, source of truth, and freshness requirements.
Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

References & Resources

Documentation

Notion Markdown Spec - Notion-flavored Markdown constraints and conversion notes
Database Properties - Practical property patterns for docs and project trackers
Notion MCP Quickstart - Hosted endpoint, local package, auth options, and usage notes

Scripts

Notion Templates - Local page and database template helpers for environments without Notion MCP access

Examples

Workspace Setup Example - Example team workspace structure using pages, databases, and review comments

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
Claude Code: keep the folder in a local skills directory or a compatible plugin source.
Codex: install or sync the folder into $CODEX_HOME/skills/notion-docs and restart Codex after major changes.

MCP Availability And Fallback

Preferred MCP Server: Notion MCP

Fallback prompt: "Use the Notion Documentation skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
Draft content locally in Markdown or JSON, then use scripts/notion-templates.js and the Notion web UI for final publishing.
Prefer page and database templates from this skill to avoid duplicate structures when working without MCP.

Related Skills

documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
documentation-patterns: Use it when the workflow also needs reusable documentation structures and templates.
documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
documentation-verification: Use it when the workflow also needs final documentation validation before publishing.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/practicalswan-agent-skills-notion-docs/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

practicalswan-agent-skills-notion-docs.ocm.jsonjson

{
  "ocm": "1",
  "id": "practicalswan-agent-skills-notion-docs",
  "kind": "skill",
  "name": "notion-docs",
  "description": "Notion workspace management via MCP - create databases, pages, comments, and knowledge bases. Use when building Notion documentation, organizing project wikis, or managing Notion content.",
  "publisher": "practicalswan",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "notion",
      "docs",
      "writing",
      "quality",
      "templates",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Notion workspace management via MCP - create databases, pages, comments, and knowledge bases. Use when building Notion documentation, organizing project wikis, or managing Notion content."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/practicalswan/agent-skills",
      "path": "notion-docs/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/practicalswan/agent-skills/blob/HEAD/notion-docs/SKILL.md",
      "key": "practicalswan/agent-skills/notion-docs/SKILL.md"
    }
  },
  "instructions": "# Notion Documentation\n\n> Tech Stack Target / Version: Notion API current version, Markdown-to-Notion transforms, and local template scripts.\n\nUse this skill when Notion is the system of record for specs, runbooks, project tracking, or knowledge management.\n\n- Leverage native parallel subagent dispatch and 200k+ context windows where available.\n\n\n## Current MCP Reality\n\nAs of March 2026, Notion documents two supported ways to use its MCP server:\n\n- Hosted remote MCP endpoint: `https://mcp.notion.com/mcp`\n- Local stdio server package: `@notionhq/notion-mcp-server`\n\nHosted mode uses OAuth. Local",
  "cost": {
    "context_tokens": 1433
  }
}

Fetch it by URL: GET /api/v1/registry/practicalswan-agent-skills-notion-docs/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.