Notion Documentation
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.
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. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
- 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.
- Do not claim an MCP operation was used when the active host does not expose it.
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
Scripts
- Notion Templates - Local page and database template helpers for environments without Notion MCP access
Examples
Related Skills
1---2name: notion-docs3description: Notion workspace management via MCP - create databases, pages, comments, and knowledge bases. Use when building Notion documentation, organizing project wikis, or managing Notion content.4---5# Notion Documentation
6
7> Tech Stack Target / Version: Notion API current version, Markdown-to-Notion transforms, and local template scripts.
8
9Use this skill when Notion is the system of record for specs, runbooks, project tracking, or knowledge management.
10
11- Leverage native parallel subagent dispatch and 200k+ context windows where available.
12
13
14## Current MCP Reality
15
16As of March 2026, Notion documents two supported ways to use its MCP server:
17
18- Hosted remote MCP endpoint: `https://mcp.notion.com/mcp`
19- Local stdio server package: `@notionhq/notion-mcp-server`
20
21Hosted 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.
22
23## Activation Conditions
24
25Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
26
27- Creating or updating Notion pages
28- Building project trackers or engineering knowledge bases
29- Organizing specs, ADRs, and onboarding docs in Notion
30- Adding review comments or using database-backed workflows
31
32## Practical Workflow
33
341. Confirm whether the client exposes the hosted Notion MCP server or a local stdio connection.
352. Read or search existing pages before creating duplicates.
363. Use databases for tracked work and pages for long-form documents.
374. Keep properties simple: owner, status, last reviewed, tags.
385. If MCP is unavailable in the current client, fall back to local content prep using the included script and templates.
39
40## Operational Notes
41
42- Official Notion guidance currently documents an average rate limit of 20 requests per second for integrations.
43- 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.
44
45## Documentation Stack Reference
46
47Inherit the shared stack from [documentation-patterns](../documentation-patterns/SKILL.md#shared-documentation-stack): 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.
48
49<!-- MCP:START -->
50
51<!-- PORTABILITY:START -->
52## Cross-Client Portability
53
54This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
55
56- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
57 workflow in project instructions when folder discovery is unavailable.
58- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
59- Codex: install or sync the folder into
60 `$CODEX_HOME/skills/notion-docs` and restart Codex after major changes.
61
62<!-- PORTABILITY:END -->
63
64## MCP Availability And Fallback
65
66Preferred MCP Server: Notion MCP
67
68- Fallback prompt: "Use the Notion Documentation skill without MCP. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
69- Draft content locally in Markdown or JSON, then use `scripts/notion-templates.js` and the Notion web UI for final publishing.
70- Prefer page and database templates from this skill to avoid duplicate structures when working without MCP.
71- Do not claim an MCP operation was used when the active host does not expose it.
72
73<!-- MCP:END -->
74
75## Anti-Patterns
76
77- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
78- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
79- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
80
81## Verification Protocol
82
83Before claiming "skill applied successfully":
84
851. Pass/fail: The Notion Docs output identifies audience, purpose, source of truth, and freshness requirements.
862. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
873. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
884. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
895. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
90
91## References & Resources
92
93### Documentation
94- [Notion Markdown Spec](./references/notion-markdown-spec.md) - Notion-flavored Markdown constraints and conversion notes
95- [Database Properties](./references/database-properties.md) - Practical property patterns for docs and project trackers
96- [Notion MCP Quickstart](./references/notion-mcp-quickstart.md) - Hosted endpoint, local package, auth options, and usage notes
97
98### Scripts
99- [Notion Templates](./scripts/notion-templates.js) - Local page and database template helpers for environments without Notion MCP access
100
101### Examples
102- [Workspace Setup Example](./examples/workspace-setup-example.md) - Example team workspace structure using pages, databases, and review comments
103
104## Related Skills
105
106- [documentation-authoring](../documentation-authoring/SKILL.md): Use it when the workflow also needs drafting structured technical or product documents.
107- [documentation-patterns](../documentation-patterns/SKILL.md): Use it when the workflow also needs reusable documentation structures and templates.
108- [documentation-quality](../documentation-quality/SKILL.md): Use it when the workflow also needs documentation review standards and quality gates.
109- [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing.
practicalswan