Notion Workspace Access

Purpose

This Skill enables direct interaction with Notion workspace using the Notion API. It provides search, retrieval, creation, and query capabilities without requiring an MCP server.

When to Use

Activate this Skill when the user:

•Mentions "Notion" or asks to work with Notion content
•Wants to search for pages or databases: "find my Marketing page in Notion"
•Needs to retrieve page content: "read the Sales Strategy page"
•Wants to create new pages: "create a new meeting notes page"
•Needs to query databases: "show me all products in the inventory database"
•References Notion URLs or page IDs
•Asks to add comments to Notion pages

When NOT to Use

•Shopify data: Use shopify skill for orders, products, inventory
•Cross-source queries: Use postgresql skill when joining Notion data with other sources
•Website analytics: Use google-analytics skill for traffic and behavior data

Setup

•Go to notion.so/my-integrations
•Click New integration
•Name it and select your workspace
•Copy the Internal Integration Secret
•Share the Notion pages/databases you want the agent to access with the integration
•
Save to .env:
- •NOTION_API_TOKEN=your-token

Markdown Support

All page creation and update operations automatically convert Markdown to formatted Notion blocks using a custom parser. Supported formats include:

•Headings (# H1, ## H2, ### H3)
•Bold, italic, ~~strikethrough~~, and inline code
•Bulleted and numbered lists (including nested)
•To-do items (- [ ] and - [x])
•Code blocks with language syntax
•Links text
•Page mentions using @[text](page-id) syntax
•Blockquotes (>)
•Dividers (---)
•Callouts (emoji or Obsidian syntax)
•Tables (| col | col |)
•Toggle blocks (<details>)
•Images ()

The script automatically handles Notion's 100-block-per-request limit by batching blocks.

Page Mentions

Use the special @[text](page-id) syntax to create clickable page mentions in Notion:

markdown

- @[Review inventory](2e7273f5-ffd9-8047-9bd0-c3f0c91909e4)
- Check @[My Task](abc12345-def6-7890-abcd-ef1234567890) for details

This creates Notion page mentions that link directly to the referenced pages.

Callouts

Two callout formats are supported:

Emoji format:

markdown

> 👍 Success
>
> This is a success message.

Obsidian format (auto-assigns emoji and color based on type):

markdown

> [!warning] Be careful
> This is a warning message.

Supported Obsidian types: info, note, tip, warning, danger, error, bug, example, quote, success, question, todo, failure, abstract, summary.

Tables

Standard markdown tables are converted to Notion tables:

markdown

| Header 1 | Header 2 |
| --- | --- |
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |

Toggle Blocks

HTML <details> tags become Notion toggle blocks:

markdown

<details>
<summary>Click to expand</summary>
Hidden content here.

- Supports nested lists
- And other blocks
</details>

Images

Standalone images on their own line:

markdown

![Alt text](https://example.com/image.png)

Available Operations

1. Search Workspace

Search for pages and databases by title or content.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts search "Marketing Strategy"

2. Get Page Content

Retrieve full content of a specific page by ID or URL.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts get-page <page-id>

3. Query Database

Query a database and retrieve records with filtering.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts query-database <database-id>

4. Create Page

Create a new page in Notion with title and content.

Usage:

bash

# Create as child of another page
deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts create-page <parent-id> "Page Title" "Page content here"

# Create in a database (supports Markdown formatting)
deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts create-database-page <database-id> "Page Title" "Markdown content here"

Note: The create-database-page command converts Markdown to properly formatted Notion blocks (headings, lists, bold, italic, etc.) and automatically handles the 100-block-per-request limit by batching.

5. Update Page

Append content to an existing page (supports Markdown formatting).

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts update-page <page-id> "Markdown content to append"

Note: The update-page command converts Markdown to properly formatted Notion blocks and appends them to the end of the page. Handles 100-block-per-request limit automatically.

6. Add Comment

Add a comment to a specific page.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts add-comment <page-id> "Comment text"

7. List Databases

List all databases in the workspace.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts list-databases

8. Get Database Schema

Get detailed schema information for a specific database, including all properties and their types.

Usage:

bash

deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts get-database-schema <database-id>

9. Scan Databases

Scan all databases in the workspace and save their schemas to static files for reference. This creates a local cache of database structures that can be used to understand database schemas without repeatedly querying the API.

Usage:

bash

deno run --allow-net --allow-env --allow-write .claude/skills/notion/scripts/notion-client.ts scan-databases

Output:

•Saves schema files to .claude/skills/notion/references/schemas/
•Each file is named {database_title}_{database_id}.json
•Contains database properties, types, and configurations

Schema file structure:

json

{
  "id": "fd81d546-0ca5-4452-8171-15bce4957403",
  "title": "Tasks",
  "url": "https://www.notion.so/fd81d5460ca54452817115bce4957403",
  "properties": [
    {
      "name": "Priority",
      "type": "select",
      "config": {
        "options": [
          {"name": "Today", "color": "red"},
          {"name": "This Week", "color": "yellow"}
        ]
      }
    }
  ]
}

When to use:

•After adding new databases to the workspace
•When schema files are missing or outdated

10. Convert Markdown to Notion Blocks

Convert markdown text to Notion API block format. Supports page mentions with @[text](page-id) syntax.

Usage:

bash

deno run --allow-net --allow-env --allow-read .claude/skills/notion/scripts/notion-client.ts md-to-notion "## Heading
- Item with @[Task Link](abc12345-def6-7890-abcd-ef1234567890)"

Output: JSON array of Notion blocks ready for API use.

11. Convert Notion Page to Markdown

Fetch a Notion page and convert all blocks to markdown. Page mentions are converted to @[text](page-id) syntax.

Usage:

bash

deno run --allow-net --allow-env --allow-read .claude/skills/notion/scripts/notion-client.ts notion-to-md <page-id>

Output: JSON with markdown field containing the converted content.

Instructions

When a user requests Notion-related operations:

•
Identify the operation type:
- •Search → use search command
- •Retrieve content → use get-page command
- •Query data → use query-database command
- •Create content → use create-page command
- •Add feedback → use add-comment command
- •List databases → use list-databases command
- •Get database schema → use get-database-schema command
- •Cache all database schemas → use scan-databases command
•
Look up database IDs and schemas from references:
- •ALWAYS check .claude/skills/notion/references/schemas/ FIRST to find databases by name
- •Schema files are named {database_name}_{database_id}.json (e.g., tasks_fd81d546.json)
- •Use Glob to search for databases: Glob(".claude/skills/notion/references/schemas/*tasks*.json")
- •
  Each schema file contains:
  - •id: The full database UUID to use in API calls
  - •title: The database name
  - •url: Direct link to the database in Notion
  - •properties: Array of all filterable/queryable properties with their types and options
•
Use schema properties for filtering:
- •Read the schema file to find available properties and their exact names
- •For select/multi_select properties, use the exact option names from config.options
- •For status properties, use option names from config.options (e.g., "Completed", "In Progress")
- •For people properties, you need the user's Notion ID (Grant Nestor = 93b12d56-258b-4e53-84d8-e826737d291b)
- •For relation properties, the config.database_id shows the related database
Example: To filter Tasks where Priority = "Today":
bash
```
# 1. Read schema to find property names and options
# From tasks_fd81d546.json: Priority is a "select" with options ["Today", "This Week", "This Month", "Next Month"]

# 2. Build filter using exact property name and option value
deno run --allow-net --allow-env --allow-read .claude/skills/notion/scripts/notion-client.ts \
  query-database-filtered fd81d546-0ca5-4452-8171-15bce4957403 \
  '{"property":"Priority","select":{"equals":"Today"}}'
```
•
Fallback to Notion Workspace Organization section:
- •If schema files are not available, check the "Notion Workspace Organization" section below
- •Extract database IDs from the URLs listed there
•
Extract parameters:
- •For search: extract search query
- •For get-page: extract page ID from URL or search if only title provided
- •For query-database: use database ID from schema file, build filter using schema properties
- •For create-page in database: use create-database-page command with database ID, extract title and content (content can be Markdown)
- •For create-page as child: use create-page command with parent page ID
- •For add-comment: extract page ID and comment text
- •For get-database-schema: use database ID from schema file
•
Execute the command:
- •Run the appropriate Deno script command
- •Pass parameters as arguments (use database ID not name)
•
Process the response:
- •Parse JSON output from the script
- •Format results in a user-friendly way
- •For page content, convert blocks to markdown
- •For database queries, format as tables
•
Handle errors gracefully:
- •If authentication fails, remind user to check NOTION_API_TOKEN
- •If page not found, suggest searching first
- •If no access, remind user to share pages with integration

Notion Workspace Organization

Your Brand Databases

•Tasks: A database of tasks, organized by assignee (team members), project, tag, priority, and status
•Projects: A database of projects that are associated with tasks
•Notes: A database of notes ranging from personal daily notes, meeting notes, working docs for projects, knowledge base articles, etc. organized by tag, date, and creator.
•Calendar: A database of events including email and SMS campaigns, photo shoots, development and production milestones, etc. organized by date, assignee, status, and tag.
•Links: A database of links to external resources such as Google Sheets, Figma pages, photo albums, Pinterest boards, etc. organized by tag.
•Tags: A database of tags to use across databases, such as Tasks, Calendar, Development Tracker, etc.
•Products: A database products to use across databases such as Development Tracker, Ad Creative, etc.
•Ad Creative: A database of ad creative briefs primarily for Meta ads organized status, product(s), audience, format, etc.
•Development Tracker: A database of products in development, from concept to delivery, organized by status, season, purchase order, style number, etc.
•Purchase Orders: A database of purchase orders for product inventory organized by season.
•Syle Numbers: Style numbers used to track product styles in Purchase Orders and Development Tracker
•People: A list of people such as influencers, content creators, models, photographers, studios, etc. organized by tag, status, location, etc.
•Tutorials: A database of tutorials such as articles and screen recordings for internal processes and workflows, focused primarily on customer service but including marketing and operations, organized by format, category, tag, and expertise level.
•Stockists: A database of retailers that sell Your Brand organized by status, location, and tag.
•Press: A database of press featuring Your Brand organized by status and tag.

Private Personal Databases

•My To Do: A database of my personal tasks organized by project, tag, priority, and status, shared with my wife Sarah.
•My Notes: A database of my personal notes, excluding journal entries, organized by tag.
•Journal: A database of my journal entries organized by date and tag.
•Projects: A database of my personal projects.
•People: A database of people I have met.
•Links: A database of my personal links.

Examples

Example 1: Search for a Page

User: "Find my Fall 2025 Catalog Shoot page in Notion"

Steps:

•Run search command: deno run --allow-net --allow-env .claude/skills/notion/scripts/notion-client.ts search "Fall 2025 Catalog Shoot"
•Parse results to find matching page
•Display page title, ID, and URL
•Optionally offer to retrieve full content

Example 2: Create a New Page

User: "Create a note for today's meetings"

Steps:

•Search schemas: Glob(".claude/skills/notion/references/schemas/*notes*.json")
•Read notes_c26c9122.json to get database ID: c26c9122-1f7b-451a-b846-7d1981338116
•Generate title: "[Today's Date in MM/DD/YY format]"
•Create outline for the meeting notes
•Run create-database-page command with the database ID
•Confirm creation and provide link to new page

Example 3: Query a Database with Filter

User: "Show me all tasks assigned to me with priority Today"

Steps:

•Search schemas: Glob(".claude/skills/notion/references/schemas/*tasks*.json")
•
Read tasks_fd81d546.json to find:
- •Database ID: fd81d546-0ca5-4452-8171-15bce4957403
- •Priority property is select type with options: "Today", "This Week", "This Month", "Next Month"
- •Assignee property is people type

•Build compound filter:

json

{"and":[
  {"property":"Priority","select":{"equals":"Today"}},
  {"property":"Assignee","people":{"contains":"93b12d56-258b-4e53-84d8-e826737d291b"}}
]}

•Run query-database-filtered command with database ID and filter
•Format results for user

Notion Blocks to Markdown Converter

The notion-to-markdown.ts module provides comprehensive conversion of Notion blocks to Markdown/HTML format. This is useful for exporting Notion content to other systems like Obsidian.

Supported block types:

•Text blocks (paragraph, headings, quote, callout)
•List blocks (bulleted, numbered, to-do with checkboxes)
•Code blocks (with language syntax)
•Toggle blocks (as HTML details/summary)
•Tables (as Markdown tables)
•Media (images, videos, files, PDFs, embeds)
•Advanced blocks (equations, synced blocks, columns)
•Links (bookmarks, link previews, page links)

Usage (as importable module):

typescript

import { blocksToMarkdown } from ".claude/skills/notion/scripts/notion-to-markdown.ts";

// Convert blocks array to Markdown string
const markdown = await blocksToMarkdown(blocks, notionClient);

Features:

•Recursive handling of nested blocks (toggle headings, list item children)
•Optional image downloading with local path mapping
•Rich text formatting preservation (bold, italic, strikethrough, code, colors)
•Callouts converted to Obsidian callout format
•Date mentions converted to Obsidian internal links

Tool Access

This Skill is restricted to:

•Read: For reading example files and documentation
•Write: For creating temporary files if needed for complex operations
•Bash: For executing Deno scripts that call the Notion API

Security Notes

•Never expose NOTION_API_TOKEN in output
•Respect Notion integration permissions (read-only if configured)
•Warn user before creating or modifying content
•The Notion API has rate limits - batch operations when possible

Troubleshooting

"Authentication failed"

•Check NOTION_API_TOKEN is set in .env
•Verify token is valid at https://www.notion.so/profile/integrations

"Page not found"

•Page may not be shared with integration
•Use "Connect to integration" in Notion page settings
•Try searching first to confirm page exists

"Permission denied"

•Integration may be read-only
•Check integration capabilities at https://www.notion.so/profile/integrations
•User may need to grant additional permissions