Notion base de connaissances d’équipe
/SKILLUtiliser Notion comme base de connaissances hiérarchique pour stratégie, décisions, métriques, contexte actif et documentation opérationnelle.
name: notion-docs
description: Hierarchical Knowledge Base via Notion API. The "brain" of your organization — strategy, priorities, decisions, metrics. Use when reading/updating Active Context, strategy docs, or operational knowledge. Triggers on "active context", "brain", "knowledge base", "strategy doc".
Brain — Notion Knowledge Base
Overview
The Knowledge Base is the "brain" of your organization — the semantic layer where strategy, priorities, metrics, and decisions live. The code repo is the "limbs" (execution). Docs in the codebase are "muscle memory" (how the limbs work).
Source of truth for: Active Context, strategy docs, billing, positioning, pricing model, platform strategy.
NOT for: Code docs (live in repo), legal docs (GDrive), spreadsheets, team artifacts.
Architecture
Hierarchical pages under a Brain root page. Five sections act as typed containers:
Brain (root page)
Active Context <- cross-cutting dashboard, stays at root
Konban <- database, managed by konban skill
Strategy/ <- why we build, how we position
Operations/ <- how the business runs day-to-day
Product/ <- what we build, platform specs
Research/ <- external knowledge, read-mostly
Archive/ <- superseded content (hidden from default index)Pages are found by title regardless of which section they're in. find_page() searches Brain root and all sections automatically.
Metadata callout format (top of each page):
Domain: Strategy | Status: Current | Updated: 2026-02-21
Summary: One-liner descriptionPage ID: BRAIN_PAGE_ID in your env file (see Credentials below)
Section Routing Table
When creating new pages, route them to the right section:
| Signal | Section | Naming | Icon |
|---|---|---|---|
| Company direction, positioning, "why" | Strategy | Descriptive title | Pick a meaningful emoji |
| Day-to-day execution, billing, playbooks | Operations | Descriptive title | Pick a meaningful emoji |
| Feature specs, platform standards | Product | Descriptive title | Pick a meaningful emoji |
| External research, market/legal analysis | Research | Research: [Topic] prefix | Pick a meaningful emoji |
| Superseded content | Archive | Keep original name | Keep original icon |
Always set an icon when creating pages: --icon "🔬" on create, or meta "Title" --icon "🔬" after the fact. Pick an emoji that reflects the page's content, not its section.
Cross-cutting dashboards (Active Context) stay at root — they don't belong to one section.
Helper Script
python3 <skill-dir>/notion-docs/notion-api.py <command> [args]Commands
# Hierarchical semantic map (THE starting point)
python3 <script> index
python3 <script> index --all # include Archive section
# Read full page as markdown (works regardless of section)
python3 <script> read "Active Context"
python3 <script> read "Billing & Invoicing" # finds it under Operations/
python3 <script> read "Title" --raw # skip metadata header
# Create new page under a section (always include --icon)
python3 <script> create "New Doc" \
--parent "Research" --icon "🔬" --domain Research --summary "One-liner" <<'NOTIONEOF'
# Content here
NOTIONEOF
# Create at Brain root (no --parent)
python3 <script> create "Cross-Cutting Doc" \
--icon "🎯" --domain Strategy --summary "..." <<'NOTIONEOF'
# Content here
NOTIONEOF
# Move page between sections (copy-and-archive — non-destructive)
python3 <script> move "Page Title" --to "Operations"
python3 <script> move "Page Title" --to "root" # back to Brain root
# Update page content — FULL REWRITE
# ABORTS if page has open comments. Use --force to override.
python3 <script> update "Title" <<'NOTIONEOF'
...full updated markdown here...
NOTIONEOF
# Patch a SINGLE SECTION (fast — only touches that section's blocks)
python3 <script> patch "Title" \
--section "Section Heading" <<'NOTIONEOF'
## Section Heading
- Updated content
NOTIONEOF
# Update metadata only (domain, summary, status, name, icon)
python3 <script> meta "Title" --summary "Updated summary"
python3 <script> meta "Old Name" --name "New Name"
python3 <script> meta "Title" --icon "🔬"
# Search (includes pages in all sections)
python3 <script> search "pricing"
# Comments
python3 <script> comments "Title"
python3 <script> comment "Title" "Reply text" -d <discussion_id>
python3 <script> comment "Title" "New comment"
# Archive (sets status to Archived in metadata)
python3 <script> archive "Old Doc"Common Mistakes (from real sessions)
**Run index before guessing page titles:**
# WRONG: read "Pricing Strategy" (guessing — page might be named differently)
# RIGHT: first run index, then use the exact title shown
python3 <script> index
python3 <script> read "SaaS Pricing Model"**Run read --raw before using patch** to see actual section headings:
# WRONG: patch "Active Context" --section "Current Sprint" (guessing section name)
# RIGHT: read first, then patch with the exact heading
python3 <script> read "Active Context" --raw
python3 <script> patch "Active Context" \
--section "Current Focus" <<'NOTIONEOF'
## Current Focus
- Updated content
NOTIONEOF**No --content flag on create or update.** Use stdin (heredoc) or --file:
# WRONG: create "Doc" --content "Some text"
# WRONG: update "Doc" --content "New text"
# RIGHT (stdin):
python3 <script> create "Doc" --parent "Research" --icon "🔬" <<'NOTIONEOF'
Content here
NOTIONEOF
# RIGHT (file):
python3 <script> update "Doc" --file /tmp/doc.mdMove Command Details
move uses copy-and-archive because the Notion API doesn't support reparenting pages. It:
- Creates a new page under the target section
- Copies all blocks from the old page
- Archives (soft-deletes) the old page
Content is preserved. Comments on the old page are lost (they stay on the archived original). Page ID changes — but all lookups are by title, so this is transparent.
Comment-Driven Editing Workflow
Team members can comment on Notion docs to give feedback. Claude reads, addresses, and replies.
**Preferred: Pull-Edit-Push with patch** (lean on tokens):
# 1. Pull doc + comments
python3 <script> read "Doc Title" --raw > /tmp/working-copy.md
python3 <script> comments "Doc Title"
# 2. Edit locally with the Edit tool — repeat as needed (~10 tokens each)
# 3. Push back SECTION BY SECTION + reply to comments
python3 <script> patch "Doc Title" \
--section "Section Name" --file /tmp/section-extract.md
# 4. Reply to addressed comments
python3 <script> comment "Doc Title" \
"Addressed: updated X per feedback" -d <discussion_id>Notion API limitation: Cannot resolve comments programmatically. Reply with what was changed; the user resolves manually in Notion.
Credentials
Stored at ~/.claude/secrets/notion.env (auto-loaded by helper):
NOTION_TOKEN— Internal integration tokenBRAIN_PAGE_ID— Root page ID (parent of all knowledge base pages). Also acceptsKH_BRAIN_PAGE_IDfor backward compatibility.
Metadata Fields
| Field | Values |
|---|---|
| Domain | Free text — use what fits your organization (e.g., Strategy, Product, Research, Operations) |
| Status | Current, Draft, Archived |
| Updated | ISO date (auto-set on update) |
| Summary | 1-2 sentence description — this IS the semantic map |
Typical Session Workflow
Startup
# Step 1: Load hierarchical semantic map
python3 <script> index
# Step 2: Load Active Context (cross-cutting priorities dashboard)
python3 <script> read "Active Context"During Session
# Read any page — find_page searches all sections automatically
python3 <script> read "Billing & Invoicing"
python3 <script> search "pricing"Session Close
python3 <script> update "Active Context" <<'NOTIONEOF'
...full updated markdown...
NOTIONEOFCRITICAL: update Destroys Comments
**update does delete-all + rewrite. This NUKES all inline Notion comments on the page.**
Decision tree:
- Page has open comments? -> Use
patch(one section at a time) - Page has no comments + changing 1-2 sections? -> Use
patch - Page has no comments + rewriting most of the doc? ->
updateis fine
Performance Notes
| Operation | Doc size | Approx time | When to use |
|---|---|---|---|
update | Small (20-30 blocks) | ~10-15s | Small docs with NO comments |
update | Large (100+ blocks) | ~45-60s | Only when rewriting the whole doc AND no comments |
patch | Any section (5-15 blocks) | ~5-15s | Preferred — preserves comments, faster |
move | Any page | ~3-30s | Copy-and-archive. Time scales with block count |
Section matching: --section matches the exact heading text (e.g., "Recent Notes", not "## Recent Notes").
Content Format
Pages store content as Notion blocks, converted from/to markdown. Supported:
- Headings (H1-H3), paragraphs, bullet/numbered lists
- Bold, italic, ~~strikethrough~~,
code, links - Code blocks, blockquotes, horizontal rules, tables
