amnafarzy/ravie/notion-brain
Claude Code and agent skill by amnafarzy/ravie
- community
Checking that the SKILL.md file is still in the repository.
Use this whenever durable knowledge should be written to or found in Notion — PRDs, decisions, runbooks, briefs, learnings — or the user says "save this", "document this", "add to the wiki". Notion writes need approval. NOT for task status — that's Linear.
Install
npx vskill@latest install amnafarzy/ravie/notion-brainSKILL.md
The same SKILL.md was published earlier as amnafarzy/ravie/notion-brain.
notion-brain
Notion is the durable knowledge base. This skill governs what goes there, how it's structured, and how it stays clean.
Purpose
Maintain Notion as the single durable source for PRDs, decisions, runbooks, operating logs, briefs, and project memory. Prevent it from becoming a duplicate task list or a chat dump.
Stack integration
Reads from:
- Notion: existing pages, databases, decisions, runbooks
- Linear: project / issue context to link from Notion
- GitHub: repo docs and ADRs to cross-link
- VPS/automation server: automation logs that feed runbook updates
- Vercel / Supabase: incident details for runbook entries
CLAUDE.md: project conventions
Writes to:
- Notion: PRDs, decision logs, runbooks, briefs, operating manuals
- Drafts: in chat first, written to Notion only after approval
Notion structure (recommended)
If your workspace doesn't have this structure yet, this skill can propose it. Don't restructure without explicit approval.
Inputs required
- Target Notion location (page or database)
- Content type: PRD / decision / runbook / brief / log / manual
- Source material (the actual content to add)
- Linked artifacts (Linear issues, GitHub PRs, decisions)
- Sensitivity: general / project-internal / client-confidential
- Review trigger date (if decision; "review in 90 days" etc.)
- Write approval
Process
1. Classify content type
Different types live in different places and have different templates:
| Content type | Lives in | Template | |
|---|---|---|---|
| PRD | Projects/[project]/PRDs | Idea-to-PRD output | |
| Decision | Projects/[project]/Decisions | ADR template | |
| Runbook | Projects/[project]/Runbooks | Step-by-step ops | |
| Daily brief | Projects/[project]/Daily briefs | Daily template | |
| Weekly review | Projects/[project]/Weekly reviews | Weekly template | |
| Pattern | Cross-project/Pattern library | Pattern template | |
| Operating manual update | Cross-project/Operating manual | (in-place edit) | |
| Imported memory | Project-specific OR Pattern library | After sanitization |
2. Check if page exists already
Before writing new content:
- Is there an existing PRD for this feature? Update vs create.
- Is there an existing runbook for this automation? Update vs create.
- Is there a decision that supersedes the one being logged?
Don't create duplicates. Update or supersede.
3. Pull linked context
For PRDs: link Linear project, GitHub repo, Figma file, related decisions. For decisions: link the PRD or issue that triggered it. For runbooks: link the GitHub automation source. For briefs: link the source data (Linear queue, PR list, etc.).
4. Write concisely, durably
Notion content is for future-you. Optimize for readability later, not for thoroughness now.
Rules:
- Lead with the conclusion / answer / current state
- Background goes lower
- Bullet points > walls of text
- Mark uncertainty explicitly (
[?]orTBD) - Date everything that might decay
5. Remove transient noise
Notion is durable. So:
- No "let me think out loud" content
- No chat-style back-and-forth
- No working notes that won't be useful in 3 months
If it's transient, it stays in chat or local notes — not Notion.
6. Add review triggers
For decisions and runbooks that may decay:
- "Review by [date]" if time-bound
- "Review when [condition]" if conditional (e.g., "when we hit 1000 users")
- No review date = "permanent" — applies to architectural foundations
7. Cross-link aggressively
Notion's value is the graph, not individual pages. Always:
- Link related decisions
- Link superseded decisions (with status)
- Link Linear project
- Link GitHub repo if the topic is technical
- Link Figma if design-relevant
8. Mark stale or superseded
When a page no longer reflects current state:
- Add a banner at top: "Superseded by [link] on [date]"
- Don't delete — historical context matters
- Move to an Archive section if needed
9. Templates
Use existing templates when adding to a database. Don't reinvent structure each time.
If a template doesn't exist for a content type you're using often, propose one (separate approval).
10. Draft before write
For non-trivial content:
- Draft in chat first
- Show full Notion-ready markdown
- Wait for explicit approval
- Then write to Notion
For tiny updates (a single line, a status change), drafting is overkill — but the skill should still note what it did.
Output format
Approval gates
Tier 1 (read-only) — querying Notion, summarizing pages: always allowed.
Tier 2 (draft) — drafting content for chat: always allowed.
Tier 3 — needs approval:
- Writing to existing Notion pages
- Creating new pages within existing databases
- Adding cross-links
- Updating runbooks
Tier 4 — needs explicit approval:
- Creating new Notion databases
- Restructuring existing databases
- Deleting pages
- Importing old memory (redact + dedupe first — checklist in
archive/skills/memory-import-sanitizer/) - Adding client-sensitive content
- Changing durable architectural decisions
Never auto:
- Storing secrets or credentials in Notion (always blocked)
- Mixing client confidential with general project memory
- Mass deletion or bulk changes
Hard rules
- Never store secrets, API keys, or credentials in Notion
- Never duplicate GitHub technical facts when linking is enough (e.g., don't paste schema definitions; link to the migration file)
- Never use Notion as a task queue — Linear is for that
- Never use Notion as a chat — that's what chat is for
- Never import old memory without redaction and deduplication (
archive/skills/memory-import-sanitizer/) - Never mix client knowledge into general operating workspace
- Never delete pages — supersede or archive instead
- Never let pages drift without review triggers if they may decay
- Never add to Notion if it's transient — chat or local notes are fine
Connects to
idea-to-prd-tracer— produces PRDs that this skill writesdecision-log-adr— produces decisions that this skill writesautomation-sre— produces runbooks that this skill writesdaily-brief— produces briefs that this skill writesskill-creator— produces patterns that this skill writeslinear-operator— task status lives in Linear, never Notion- Archived references:
archive/skills/holds memory-import-sanitizer, system-of-record-governance, and client-boundary-guard checklists
Common failure modes
Notion becomes a chat archive — Pages full of "I think we should..." and "let me explore..." Notion is for durable. Move exploration to chat or scratch notes.
Duplicate PRDs — Two PRDs for the same feature because no one searched. Always check before creating.
Stale runbooks — Runbook says do X, but reality is now Y. Add review triggers. During weekly review, check runbooks against actual practice.
No cross-linking — Pages exist but you can't find them. The graph is the value. Link aggressively.
Notion competes with Linear — Tasks live in Notion as bullet points. They drift from Linear. Linear is the task system. Notion only describes tasks at the project level (in PRDs, decisions, briefs).
Client data in general workspace — A project PRD references client X by name. That's a leak. Keep client names out of the general workspace (checklist: archive/skills/client-boundary-guard/).
Death by template — Every template creates 8 sections, most empty. Templates should encode minimums, not exhaustive structure.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/notion-brain/SKILL.md
Popularity
- Repository stars
- 3
- 7-day trend score
- 7
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/amnafarzy/ravie/notion-brain)