메뉴
Working with Notion documents via the Notion MCP. Covers Notion’s custom markdown syntax, content updates, tables, callouts, highlighting, database pages, and the comments-based review workflow. Load this before ANY Notion content work.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Keep a live interactive chat session coming back to itself, visibly, after a usage/session cap interrupts it, never a silent background process. Invoke with /qq-cap-resume, or say “keep this session alive,” “resume yourself after the cap,” “don’t go dark on me,” any time a long interactive burn needs to survive a 5-hour session cap or ride out to a weekly reset without leaving you staring at a dead thread.
The unbounded end of the AFK spectrum: spend whatever it takes for quality, budget isn’t the constraint. Stand up a self-healing, fully-autonomous “kitchen-sink max-effort” campaign for a big multi-day initiative: resilience first, creative meta strategy, workflows spawning workflows, audit-gated quality, a phone-glanceable status surface with a proud wins list, and a long living tasklist. Invoke when you say “go HAM”, “go-ham”, “go afk ham”, “qq-go-afk-ham”, “kitchen sink”, “blow me away”, “use all the quota”, or hand it a large ambitious build to run autonomously for hours or days. For the frugal end, use `qq-go-afk-lean`; for the adaptive middle, use `qq-go-afk-smart`.
The adaptive middle of the AFK spectrum: picks the right model task by task, moment by moment, instead of committing to either extreme. Stand up a calm, self-healing, fully-autonomous overnight worker for a well-scoped punch list: the top-tier model writes strict specs and does quality control, cheap and free models do the grunt work, one bounded task per cycle, each one deployed and live-verified, a phone-glanceable status surface, and a durable done log. Invoke when you say “go afk smart”, “go-afk-smart”, “qq-go-afk-smart”, “go smart”, “bounded overnight”, “delegate and verify overnight”, or hand it a finite, well-specified backlog (a punch list, a rollout, a sweep) to grind down autonomously while you sleep, without the kitchen-sink fan-out of go HAM. For the unbounded end, use `qq-go-afk-ham`; for the frugal end, use `qq-go-afk-lean`.
The moment a real, avoidable mistake happens, name it plainly, root-cause the general class of it rather than just this one instance, and fix it at a level that prevents a repeat, not a note that gets written and forgotten. Then, before starting work that looks like it could repeat that shape, check the log first. A second occurrence of the same mistake means the note wasn’t enough, and it needs to become a real check instead of a reminder. Invoke with /ww-mistake-ledger, or say “log this mistake,” “close the loop on this,” “add this to the mistake log,” “check the mistake log first,” right after a preventable error, or right before starting work that resembles one already logged.
Ask what would make this fail before you build it, not after. A one-question design-time gate, imagine it’s already broken three months from now, work backward to the most likely cause, and let the answer change the plan instead of just getting noted and ignored. Works on code, an automation, a process, or a decision. Invoke with /ww-premortem, or say “what breaks this in three months,” “pre-mortem this,” “why would this fail,” “before I build this,” at the moment you’re about to commit to an approach, not after you’ve already started.
Before filling a gap in what you know with a guess, check whether the guess is load-bearing. If getting it wrong would mean redoing real work, or building on a false premise, ask a real question with concrete options instead of assuming silently. If it’s genuinely low-stakes, state the assumption out loud and keep moving rather than stalling on it. Works on any ambiguous request, with or without an AI agent involved. Invoke with /ww-questioning, or say “wait, let me ask first,” “is this load-bearing,” “check before I guess,” “clarify before building,” whenever a request has more than one reasonable reading and you’re about to just pick one.
| name | ww-notion-docs |
| description | Working with Notion documents via the Notion MCP. Covers Notion’s custom markdown syntax, content updates, tables, callouts, highlighting, database pages, and the comments-based review workflow. Load this before ANY Notion content work. |
Part of Claude Code operator skills: a collection of skills for running a real Claude Code setup.
The problem: Notion’s block editor does not speak standard markdown. Pipe tables silently fail to render. Escaped \n sequences show up as literal backslash-n in the page instead of a line break. Curly braces meant to set a block color end up as visible text if they get escaped wrong. None of these fail loudly, they just fail quietly, and you don’t find out until you look at the page and something is broken.
This skill documents Notion’s actual markdown flavor so content stops silently failing to render right, plus the update patterns (fetch-before-edit, update_content vs replace_content) and the comments-based review workflow that make Notion usable as a real collaboration surface instead of a one-way publish target.
Notion uses its OWN markdown flavor, not standard markdown. Before writing any content:
ReadMcpResourceTool → server: "Notion" (or whatever your Notion MCP connection is named), uri: "notion://docs/enhanced-markdown-spec"
Do this every session. Don’t rely on memory of the spec. It’s cheap and prevents silent formatting failures.
<table> HTML tags, NOT pipe | tables. Pipe tables silently fail to render.<callout icon="emoji" color="Color"> tags, with Notion markdown inside (not HTML).{color="yellow_bg"} at end of a block, or <span color="yellow_bg">text</span> inline.<empty-block/> when you need vertical space.---\ * ~ $ [ ] < > { } | ^`, all need backslash escaping in body text.gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg
<table header-row="true">
<tr>
<td>Header 1</td>
<td>Header 2</td>
</tr>
<tr>
<td>Data</td>
<td>Data</td>
</tr>
</table>
<callout icon="⚠️" color="yellow_bg">
Content here. Use Notion markdown inside, not HTML.
</callout>
When asked to highlight changes or show what’s new:
{color="yellow_bg"} at end of changed blocks<span color="yellow_bg">changed text</span> for changes within unchanged blocksALWAYS notion-fetch the page before doing notion-update-page with update_content. The old_str must match the page’s current content exactly. Stale strings won’t match and the update silently fails.
replace_content vs update_content| Method | Use when | Risk |
|---|---|---|
replace_content | New page, or full rewrite you control | Blows away ALL existing content including reviewer edits |
update_content | Targeted edits to specific sections | Safe. Only touches matched strings |
Default to update_content. Only use replace_content for pages you just created or when a full rewrite is explicitly intended.
The new_str parameter (and replace_content body) must use REAL newlines, not \n escape sequences. Escaped newlines render as literal \n text in Notion.
data_source_id (not database_id) when the database has multiple data sourcesA reasonable shape for a database of client-facing deliverables and review workflow, if you’re setting one up from scratch:
Find your own database’s data_source_id by fetching it first, and swap it in wherever this skill (or a skill that calls into it) references one.
The reviewer comments on blocks in Notion. Claude reads and responds via MCP.
notion-get-comments with include_all_blocks: truetext-context showing which text they’re anchored toupdate_content, using the text-context to locate the right sectionComments are not optional. They ARE the review interface. The reviewer reads the doc in Notion and sees Claude’s comments explaining changes. Without comments, changes are invisible and the reviewer has to re-read the entire document to find what moved. That’s unacceptable cognitive load.
When to add comments:
update_content call: comment on the changed textreplace_content call: comment on each major section that changedThis is the preferred review workflow for deliverables. Don’t ask the reviewer to paste feedback into chat.
When archiving previous versions below the current content, include the full text of each version, not just a summary. Reviewers use the archive for reference and comparison. One-line descriptions are not enough.
Always set a relevant emoji icon on every Notion page you create. Pick an icon that matches the content type:
| Content type | Icon |
|---|---|
| Proposal / pitch | 🤝 |
| Strategy / brainstorm | 💡 |
| Audit / analysis | 🔍 |
| Messaging framework | 🎯 |
| Interview questions | 🎤 |
| Content calendar | 📅 |
| Kickoff / project plan | 🚀 |
| Draft (general) | ✏️ |
| Meeting notes | 📝 |
| Pricing / financial | 💰 |
| Competitive analysis | ⚔️ |
Set via the icon parameter on create-pages or update-page. Never leave the default blank page icon.
replace_content (full rewrite)Use replace_content when:
After a full rewrite, add tightly contextual comments (see below) explaining each major change.
When you need to add new content at the beginning of an existing page without replacing everything:
update_content with old_str matching that first blocknew_str to: new content + original first blockThis effectively prepends without touching the rest of the page. Safe for pages with active comments (comments on untouched blocks survive).
When archiving previous versions below current content:
<empty-block/> tags before the archive section--- divider## Previous versions (archive)Anchor comments to specific selected text, not whole sections or headings. Use selection_with_ellipsis with ~10 chars from start + ellipsis + ~10 chars from end. Comments explain what changed and why at the exact point of change.
Bad: comment on ## Engagement model heading saying “this section was rewritten”
Good: comment on fixed price, not...based rate saying “v4.0: Replaced commitment-discounted rate language. Fixed-price for deliverables, not time-based billing.”
Some Notion integrations (including the official Claude integration) show comments under their own name and icon, distinct from the human reviewer’s comments. Check what your specific integration shows before assuming you need to prefix comments with “Claude:”. If the identity is already visible in the Notion UI, a prefix is redundant.
\n literals instead of real newlines. Content renders as one giant block. Every newline must be an actual line break in the string.| Col |. They don’t render in Notion. Use <table> tags.update_content. old_str won’t match current content. Always fetch first.replace_content when update_content would work. Destroys reviewer edits. Default to update_content.[audience] must be \[audience\] or Notion interprets it as a link/mention.{color="yellow_bg"} is a block attribute. replace_content preserves existing block colors. update_content that includes {color="default"} can work to clear colors, but if the braces get escaped they become visible literal text \{color="yellow_bg"\} in the document. Safest approach: Avoid setting block colors unless you plan to manage them carefully. If you must clear a block color, use {color="default"} via update_content. If literal escaped color tags appear in content, match them with escaped braces in old_str: \\{color="yellow_bg"\\}.icon parameter on create-pages or update-page instead of an emoji character.