SuperAPI AI Directory
Partner中文AI newsFavorites
SkillsNotion Mastery

Notion Mastery

Office & productivity

View repository

Updated 10-18 22:13

About this skill

Notion Mastery

Create, design, and automate in Notion using MCP tools and the REST API. Build professional-looking pages with proper visual design patterns.

Page Design Principles

For complete design patterns and page templates, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/page-design-patterns.md.

Making Pages Look Professional

Notion pages look best when they follow these principles:

  • Lead with a callout — Use a callout block at the top with an emoji icon and brief description. Sets the tone and provides immediate context.
  • Use toggle headings — ## Heading {toggle="true"} keeps pages scannable. Users expand sections they care about.
  • Columns for side-by-side content — Two or three columns using <columns> for dashboards, comparison views, or separating related content.
  • Non-obtrusive TOC — Place <table_of_contents/> inside a toggle or callout, not at the very top. Or place it in a column beside content.
  • Callouts for emphasis — Color-coded callouts for tips, warnings, notes, prerequisites. Use sparingly.
  • Dividers between sections — --- creates visual breathing room between major sections.
  • Alternating block types — Mix headings, text, callouts, tables, and images. Avoid walls of text.
  • Consistent color scheme — Pick 2-3 colors and use them throughout. Blue for info, yellow for warnings, green for success.

Layout Patterns

Hero pattern — Callout with icon + brief intro, then divider, then content:

::: callout {icon="🚀" color="blue_bg"}
**Project Dashboard** — Track progress, milestones, and blockers at a glance.
:::
---

Two-column dashboard — Key metrics on left, action items on right:

<columns>
  <column>
    ## 📊 Metrics {toggle="true"}
      Content...
  </column>
  <column>
    ## ✅ Actions {toggle="true"}
      Content...
  </column>
</columns>

Toggle sections — Clean, expandable page:

## 📋 Overview {toggle="true"}
  Content here...
## 🎯 Goals {toggle="true"}
  Content here...
## 📝 Notes {toggle="true"}
  Content here...

Notion-Flavored Markdown

For the complete block catalog and syntax, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/notion-markdown-spec.md and ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/block-catalog.md.

Notion uses a custom Markdown dialect for page content. Key syntax:

Block Colors

Any block accepts {color="Color"} at the end of its first line:

  • Text colors: gray, brown, orange, yellow, green, blue, purple, pink, red
  • Background colors: gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg

Key Block Types

  • Callout: ::: callout {icon="💡" color="yellow_bg"}\nContent\n:::
  • Columns: <columns><column>Left</column><column>Right</column></columns>
  • Toggle: <details><summary>Label</summary>\n\tContent\n</details>
  • Toggle heading: ## Heading {toggle="true"}
  • Table: <table header-row="true"><tr><td>A</td><td>B</td></tr></table>
  • Table of contents: <table_of_contents/>
  • Synced block: <synced_block>\n\tContent\n</synced_block>
  • Code block: ```language\nCode\n```
  • Equation: $$\nLaTeX\n$$
  • Image: ![Caption](URL)
  • Divider: ---
  • Meeting notes: <meeting-notes>\n\tTitle\n\t<notes>\n\t\tContent\n\t</notes>\n</meeting-notes>

Rich Text Formatting

  • Bold: **text**, Italic: *text*, Strikethrough: ~~text~~
  • Underline: <span underline="true">text</span>
  • Color: <span color="blue">text</span> or <span color="red_bg">text</span>
  • Inline code: `code`, Inline math: $equation$
  • Link: [text](url), Mention: <mention-page url="...">Title</mention-page>

Databases

For complete database reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/database-mastery.md.

Core Concepts

  • Properties — Columns defining data schema: Title, Text, Number, Select, Multi-select, Date, Person, Files, Checkbox, URL, Email, Phone, Formula, Relation, Rollup, Created time, Last edited time, Created by, Last edited by, Status, AI autofill
  • Views — Different ways to visualize the same data: Table, Board, Calendar, Timeline, Gallery, List
  • Filters — Narrow visible rows by property conditions
  • Sorts — Order rows by property values
  • Templates — Pre-built page content for new database entries
  • Relations — Link entries across databases (one-to-many, many-to-many)
  • Rollups — Aggregate related data (count, sum, average, date range, etc.)
  • Linked databases — Show a filtered view of another database on any page

Database via MCP

Use notion-create-database to create databases. Use notion-fetch to read schema. Use notion-update-data-source to modify schema.

Notion Formulas

For the complete formula reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/formula-language.md.

Notion formulas use a functional syntax (not VB.NET, not Excel):

// Days until deadline
dateBetween(prop("Due Date"), now(), "days")

// Status emoji
if(prop("Status") == "Done", "✅",
  if(prop("Status") == "In Progress", "🔄", "⏳"))

// Progress percentage
round(prop("Completed Tasks") / prop("Total Tasks") * 100)

Key Formula Functions

  • Logic: if(), and(), or(), not(), empty()
  • Math: add(), subtract(), multiply(), divide(), mod(), pow(), round(), ceil(), floor(), abs(), min(), max()
  • Text: concat(), join(), slice(), length(), contains(), replace(), replaceAll(), test(), upper(), lower(), repeat(), padStart(), padEnd(), trim()
  • Date: now(), today(), dateAdd(), dateSubtract(), dateBetween(), formatDate(), minute(), hour(), day(), date(), month(), year()
  • Lists: at(), first(), last(), slice(), concat(), sort(), reverse(), map(), filter(), every(), some(), find(), findIndex(), flat(), length(), includes()

AI Features

For complete AI feature reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/ai-features.md.

  • AI Autofill property — Database property that uses AI to fill values based on page content
  • AI blocks — Inline AI-generated content within pages
  • Meeting notes — <meeting-notes> blocks with AI summaries and transcripts
  • AI search — Semantic search across workspace and connected sources via MCP search tool

MCP Tools

For detailed MCP usage patterns, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/mcp-tools-guide.md.

Available Notion MCP tools:

  • notion-search — Search pages, databases, users across workspace
  • notion-fetch — Read full page content, database schema, data source details
  • notion-create-pages — Create one or more pages with content and properties
  • notion-update-page — Update properties, replace/insert content, apply templates, verify pages
  • notion-move-pages — Move pages or databases to new parents
  • notion-duplicate-page — Duplicate existing pages
  • notion-create-database — Create new databases with schema
  • notion-update-data-source — Modify database schema and properties
  • notion-create-comment — Add comments to pages or specific blocks
  • notion-get-comments — Read comments and discussions
  • notion-get-teams — List teamspaces
  • notion-get-users — List workspace members

MCP Workflow Pattern

  1. Search to find existing content: notion-search
  2. Fetch to read full details: notion-fetch
  3. Create or update to make changes: notion-create-pages or notion-update-page
  4. Verify the result by fetching again

REST API

For API endpoints and patterns, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/api-reference.md.

The Notion API (api.notion.com) is useful when MCP tools don't cover a scenario:

  • Bulk operations — Creating hundreds of pages in batches
  • Webhooks — Listening for changes
  • Programmatic database queries — Complex filtering with the API's filter object
  • Block-level manipulation — Appending, moving, and deleting individual blocks
  • User management — Bot user info, workspace member details

Authentication: Bearer token (integration token or OAuth). Base URL: https://api.notion.com/v1/.

Troubleshooting

For common errors and diagnostic steps, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/troubleshooting.md.

Covers MCP tool errors (page not found, rate limits, invalid content), page design issues (toggle content not nesting, callouts not rendering), database problems (formula errors, relation issues), API-specific issues, and performance diagnostics.

Reference Files

File Path Content
Notion Markdown Spec ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/notion-markdown-spec.md Complete Notion-flavored Markdown syntax reference
Page Design Patterns ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/page-design-patterns.md Visual design principles, layouts, color schemes, professional page patterns
Block Catalog ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/block-catalog.md Every block type with syntax, use cases, and styling tips
Database Mastery ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/database-mastery.md Views, relations, rollups, linked DBs, templates, automations
Formula Language ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/formula-language.md Complete Notion formula syntax, functions, and patterns
MCP Tools Guide ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/mcp-tools-guide.md How to use each Notion MCP tool effectively
API Reference ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/api-reference.md REST API endpoints, authentication, SDK patterns
AI Features ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/ai-features.md AI blocks, meeting notes, autofill, AI search, connected sources
Troubleshooting ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/troubleshooting.md Common errors, diagnostic steps, and performance issues

Example Files

File Path Content
Page Templates ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/examples/page-templates.md Complete page templates: dashboard, wiki, meeting notes, project tracker
Database Schemas ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/examples/database-schemas.md Production database designs for common use cases
Design Showcase ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/examples/design-showcase.md Beautiful page layouts with full Notion Markdown source
API Automation ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/examples/api-automation.md TypeScript examples for common automation patterns