Notion Writer

Notion Writer Skill

An intelligent AI skill that transforms unstructured notes into beautifully organized Notion pages with automatic formatting, categorization, and proper hierarchy.

🚀 Quick Usage

For AI Agents calling this skill:

# Upload a note to Notion
python scripts/write_to_notion.py \
  --content "Your note content here" \
  --title "Project Ideas"

# Upload from file
python scripts/write_to_notion.py \
  --file "notes.md" \
  --auto-organize

What it does:

• ✅ Structures unorganized notes intelligently
• ✅ Creates proper Notion page hierarchy
• ✅ Formats content with headers, lists, and blocks
• ✅ Automatically categorizes and tags content
• ✅ Supports markdown conversion to Notion blocks
• ✅ Handles images, code blocks, and rich media

Output: Organized Notion page with URL for immediate access.

Core Capabilities

This skill provides complete note organization and Notion integration:

1. ✅ Content Structuring - Analyzes and organizes unstructured notes
2. ✅ Smart Formatting - Converts markdown to Notion blocks automatically
3. ✅ Hierarchy Management - Creates parent-child page relationships
4. ✅ Auto-Categorization - Tags and categorizes content intelligently
5. ✅ Batch Processing - Handles multiple notes in one operation
6. ✅ Template Support - Uses predefined templates for consistent formatting

When to Use This Skill

Use this skill when the user wants to:

• Save notes, ideas, or documentation to Notion
• Organize messy text into structured pages
• Convert markdown files to Notion pages
• Create meeting notes, project docs, or knowledge bases
• Batch upload multiple notes with consistent formatting
• Maintain a personal knowledge management system
• Archive research, articles, or learning materials

Quick Start - For AI Agents

First Time Setup

# Navigate to skill directory
cd ~/.claude/skills/notion-writer

# Run interactive setup (guides user through API configuration)
python scripts/setup.py

The setup script will:

1. Guide user to create Notion integration
2. Help obtain API key and database ID
3. Test connection to Notion
4. Save configuration securely
5. Create sample page to verify setup

Simple Usage

# Write a simple note
python scripts/write_to_notion.py \
  --content "Today's standup: Completed API integration, working on frontend"

# Upload markdown file with auto-organization
python scripts/write_to_notion.py \
  --file "meeting_notes.md" \
  --auto-organize \
  --template meeting

# Batch upload multiple files
python scripts/batch_upload.py \
  --directory "./notes" \
  --pattern "*.md"

Complete Workflow

1. Understand User Intent & Gather Information

When the user wants to save notes to Notion, extract and confirm:

Required Information:

• Note content: The actual text/notes to save
• Note title: What to name the page (or auto-generate)
• Organization: Where in Notion to save it
• Format preferences: Any specific formatting needs
• Template: Use predefined template or custom format

Example User Requests:

• "Save this to Notion: [content]"
• "Organize these meeting notes in Notion"
• "Upload my project ideas to my knowledge base"
• "Convert this markdown file to a Notion page"

What YOU Must Do:

• Extract the content to be saved
• Identify if it's raw text, markdown, or a file path
• Ask for title if not provided (or generate intelligently)
• Determine target database/parent page
• Identify appropriate template if applicable

2. Analyze and Structure Content

CRITICAL: Don't just dump raw text into Notion - structure it properly!

Content Analysis Steps:

1. Parse the content - Understand the structure

   • Is it meeting notes? (date, attendees, topics, action items)
   • Is it a project doc? (overview, goals, tasks, timeline)
   • Is it research? (summary, key findings, references)
   • Is it a daily journal? (date, events, reflections)

2. Extract key components:

   • Headers and subheaders
   • Lists (ordered/unordered)
   • Code blocks
   • Important highlights or quotes
   • Action items or TODOs
   • Links and references

3. Organize hierarchically:

   • Main title
   • Section headers (H1, H2, H3)
   • Body paragraphs
   • Lists and nested items
   • Callouts and highlights

Structure Examples:

✅ Good Structure (Meeting Notes):

📅 Daily Standup - 2026-02-09

## Attendees
- Alice (PM)
- Bob (Dev)
- Charlie (Design)

## Updates
### Alice
- Completed user testing
- Starting sprint planning

### Bob
- Fixed critical bug in payment flow
- Working on API integration

## Action Items
- [ ] Alice: Schedule sprint planning meeting
- [ ] Bob: Complete API docs by Friday
- [ ] Charlie: Share design mockups

## Blockers
None reported

❌ Bad Structure (Raw Dump):

daily standup alice completed user testing starting sprint planning bob fixed bug working on api charlie no updates action items alice schedule meeting bob write docs

3. Convert to Notion Blocks

Transform structured content into Notion block format:

Supported Block Types:

• heading_1, heading_2, heading_3 - Headers
• paragraph - Regular text
• bulleted_list_item - Unordered list
• numbered_list_item - Ordered list
• to_do - Checkbox items
• code - Code blocks with syntax highlighting
• quote - Blockquotes
• callout - Highlighted callouts (info, warning, etc.)
• divider - Section separators
• image - Embedded images
• bookmark - Link previews

Conversion Rules:

• # Header → heading_1
• ## Header → heading_2
• - Item → bulleted_list_item
• 1. Item → numbered_list_item
• - [ ] Task → to_do (unchecked)
• `code` → inline code
• ```code``` → code block
• > Quote → quote
• ![alt](url) → image
• [link](url) → embedded link

4. Apply Smart Enhancements

Add Value Through AI Processing:

1. Auto-Tagging:

   • Detect topics: #project, #meeting, #idea
   • Identify people: @mentions
   • Recognize dates and deadlines
   • Extract keywords

2. Metadata Generation:

   • Created date
   • Last updated
   • Category
   • Status (Draft/In Progress/Complete)
   • Priority (if applicable)

3. Smart Formatting:

   • Add emoji icons to headers 📋 📊 💡
   • Highlight action items
   • Format dates consistently
   • Create table of contents for long docs

4. Link Related Content:

   • Reference similar existing pages
   • Link to related projects
   • Connect meeting notes in series

5. Upload to Notion

Execute the upload with proper error handling:

python scripts/write_to_notion.py \
  --content "<structured_content>" \
  --title "Well-Formed Title" \
  --database-id "<database_id>" \
  --tags "meeting,project-x,urgent"

What YOU Must Do:

1. Use configured API credentials
2. Target correct database/parent page
3. Set appropriate properties (tags, status, etc.)
4. Handle errors gracefully (API limits, permissions, etc.)
5. Verify upload success
6. Return the page URL

Error Handling:

• ❌ Invalid API key → Guide user through setup again
• ❌ Database not found → List available databases
• ❌ Permission denied → Check integration permissions
• ❌ Rate limit → Wait and retry with backoff
• ❌ Invalid content → Show which blocks failed

6. Provide Clear Feedback to User

CRITICAL: Always confirm success and provide the link!

Your Report Must Include:

✅ Success Report Format:

✅ Successfully uploaded to Notion!

📄 Page: "Daily Standup - 2026-02-09"
🔗 URL: https://notion.so/workspace/page-id
📁 Location: Project X > Meetings

Content Summary:
- 3 attendees
- 6 updates logged
- 3 action items created
- 0 blockers

Next Steps:
- View page: [Click here](url)
- Edit page: Open in Notion app
- Share: Click share button in Notion

❌ Error Report Format:

❌ Failed to upload to Notion

Error: Invalid API credentials

What Happened:
- API returned 401 Unauthorized
- Your API key may have expired

Recommended Actions:
1. Run setup again: python scripts/setup.py
2. Check integration permissions in Notion
3. Verify database is shared with integration

Need Help? See TROUBLESHOOTING.md

📊 Always Include:

• Clear success/failure indicator
• Page title and URL (if successful)
• Content summary (# of sections, items, etc.)
• Location in Notion hierarchy
• Next steps or action items
• Error details and fixes (if failed)

7. Advanced Features

Batch Processing:

# Upload entire directory of notes
python scripts/batch_upload.py \
  --directory "./meeting_notes" \
  --template meeting \
  --auto-organize \
  --tags "meetings,2026"

Template Usage:

# Use predefined template
python scripts/write_to_notion.py \
  --content "..." \
  --template project_brief

# Available templates:
# - meeting: Meeting notes with agenda/action items
# - project_brief: Project overview template
# - daily_journal: Daily reflection template
# - research: Research notes with references
# - task_list: Task management template

Smart Organization:

# Let AI decide best organization
python scripts/write_to_notion.py \
  --file "notes.md" \
  --auto-organize \
  --smart-categorize

Environment Setup

1. Install Dependencies

cd notion-writer
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Interactive Setup (Guides User Through API Configuration)

python scripts/setup.py

Setup Process:

1. Create Notion Integration

   • Opens: https://www.notion.so/my-integrations
   • Guides user to create new integration
   • Explains required permissions

2. Get API Key

   • Shows where to copy "Internal Integration Token"
   • Validates format
   • Tests connection

3. Get Database ID

   • Guides user to share database with integration
   • Explains how to find database ID from URL
   • Lists available databases

4. Test Connection

   • Creates test page in database
   • Verifies all permissions work
   • Shows success confirmation

5. Save Configuration

   • Stores config in ~/.notion-writer/config.json
   • Securely saves API key
   • Creates example templates

3. Manual Configuration (Optional)

Create config.json:

{
  "notion_api_key": "secret_xxx",
  "default_database_id": "database-id-here",
  "default_parent_page_id": null,
  "templates_dir": "./templates",
  "preferences": {
    "auto_tag": true,
    "add_emoji": true,
    "create_toc": true,
    "smart_formatting": true
  }
}

4. Verify Installation

python scripts/test_connection.py

Expected output:

✅ Connected to Notion API
✅ Database accessible
✅ Integration has proper permissions
✅ Test page created successfully

Your Notion Writer is ready to use!

Notion Integration Setup Guide

Step 1: Create Notion Integration

1. Go to https://www.notion.so/my-integrations
2. Click "+ New integration"
3. Name it: "Note Writer"
4. Select your workspace
5. Copy the "Internal Integration Token" (starts with secret_)

Step 2: Share Database with Integration

1. Open the Notion database where you want to save notes
2. Click "..." (three dots) in the top right
3. Scroll to "Connections"
4. Click "+ Add connection"
5. Select your "Note Writer" integration

Step 3: Get Database ID

Method 1 (From URL):

• Open your database in Notion
• Look at the URL: notion.so/workspace/DATABASE_ID?v=...
• Copy the DATABASE_ID part (32 character hex string)

Method 2 (Using script):

python scripts/list_databases.py

This will list all databases your integration can access.

Step 4: Configure the Skill

Run the interactive setup:

python scripts/setup.py

Or manually edit config.json with your credentials.

Usage Examples

Example 1: Quick Note

User: "Save this to Notion: Had a great idea for the homepage redesign - use a card-based layout with infinite scroll"

Agent Actions:

1. Extract content and context
2. Structure as an idea note
3. Add appropriate tags
4. Upload to Notion

Agent Response:

✅ Saved to Notion!

📄 "Homepage Redesign Idea"
🔗 https://notion.so/...
🏷️ Tags: idea, design, homepage

Your idea has been saved and formatted. I added it to your Ideas database with automatic categorization.

Example 2: Meeting Notes

User: "Organize these meeting notes in Notion: [pastes unstructured text]"

Agent Actions:

1. Parse unstructured text
2. Identify: date, attendees, topics, action items
3. Structure using meeting template
4. Add checkboxes for action items
5. Upload with proper formatting

Agent Response:

✅ Meeting notes organized and uploaded!

📅 "Weekly Team Sync - Feb 9, 2026"
🔗 https://notion.so/...
📁 Location: Meetings > 2026 > February

Structured Content:
- 5 attendees identified
- 3 main discussion topics
- 4 action items (with checkboxes)
- 2 decisions recorded

All action items have been formatted as checkboxes so you can track completion directly in Notion.

Example 3: Markdown File Upload

User: "Convert my project README to a Notion page"

Agent Actions:

1. Read the markdown file
2. Parse headers, code blocks, lists
3. Convert to Notion blocks
4. Preserve formatting and structure
5. Upload with proper hierarchy

Agent Response:

✅ README converted and uploaded!

📄 "Project XYZ - Documentation"
🔗 https://notion.so/...

Conversion Summary:
- 8 sections with headers
- 3 code blocks (with syntax highlighting)
- 2 task lists (12 items total)
- 5 external links preserved

Your README is now a beautifully formatted Notion page with table of contents.

Example 4: Batch Upload

User: "Upload all my weekly notes from ./notes folder to Notion"

Agent Actions:

1. Scan directory for markdown files
2. Process each file individually
3. Auto-categorize by week/month
4. Create proper hierarchy
5. Upload in batch with progress tracking

Agent Response:

✅ Batch upload complete!

📁 Processed: ./notes
📄 Files uploaded: 12
⏱️ Time taken: 45 seconds

Organization:
└─ Weekly Notes
   ├─ 2026-02-03 to 2026-02-09 (4 notes)
   ├─ 2026-01-27 to 2026-02-02 (5 notes)
   └─ 2026-01-20 to 2026-01-26 (3 notes)

All notes have been organized by week and uploaded to your Weekly Notes database.
View: https://notion.so/...

Templates

Available Templates

1. Meeting Notes Template

# 📅 [Meeting Title] - [Date]

## Attendees
- Person 1
- Person 2

## Agenda
1. Topic 1
2. Topic 2

## Discussion Notes
[Main content]

## Action Items
- [ ] Task 1 (@person)
- [ ] Task 2 (@person)

## Decisions Made
- Decision 1
- Decision 2

## Next Meeting
Date: [Next date]

2. Project Brief Template

# 📋 [Project Name]

## Overview
[Brief description]

## Goals
- Goal 1
- Goal 2

## Timeline
- Milestone 1: [Date]
- Milestone 2: [Date]

## Team
- Role 1: Person
- Role 2: Person

## Resources
- [Link 1]
- [Link 2]

## Status
🟢 On Track | 🟡 At Risk | 🔴 Blocked

3. Daily Journal Template

# 📔 [Date]

## 🌅 Morning Thoughts
[Reflections]

## ✅ Accomplished Today
- Task 1
- Task 2

## 💡 Learnings
[What I learned]

## 🎯 Tomorrow's Focus
- Priority 1
- Priority 2

## 🙏 Gratitude
[Things I'm grateful for]

Creating Custom Templates

# Create new template
python scripts/create_template.py \
  --name "my_template" \
  --structure "path/to/template.md"

# List available templates
python scripts/list_templates.py

Troubleshooting

Issue: Setup fails with "Invalid API Key"

Solutions:

• Verify you copied the complete token (starts with secret_)
• Check for extra spaces or line breaks
• Ensure integration is active in Notion settings
• Try generating a new integration token

Issue: "Database not found" error

Solutions:

• Verify database ID is correct (32 hex characters)
• Ensure database is shared with your integration
• Check if you have the right workspace selected
• Try using scripts/list_databases.py to find correct ID

Issue: "Insufficient permissions" error

Solutions:

• Go to Notion integration settings
• Ensure these capabilities are enabled:
  • Read content
  • Update content
  • Insert content
• Re-share database with integration
• Check workspace permissions

Issue: Content not formatting correctly

Solutions:

• Check markdown syntax is valid
• Ensure code blocks use triple backticks
• Verify image URLs are accessible
• Test with simpler content first
• Check logs: tail -f logs/notion_writer.log

Issue: Upload is slow or times out

Solutions:

• Check internet connection
• Notion API may be experiencing issues
• Try uploading smaller chunks
• Enable retry logic: --retry 3
• Check Notion status: https://status.notion.so

API Rate Limits

Notion API has rate limits:

• 3 requests per second per integration
• 1000 requests per minute (for batch operations)

The skill handles this automatically:

• Implements exponential backoff
• Queues requests properly
• Shows progress for large batches
• Retries failed requests intelligently

Security & Privacy

Best Practices:

• ✅ API keys stored in ~/.notion-writer/config.json (not in code)
• ✅ Config file has restricted permissions (600)
• ✅ Never commit credentials to version control
• ✅ Use environment variables for shared systems
• ✅ Regularly rotate API keys
• ✅ Only grant minimum required permissions

Data Handling:

• All data sent directly to Notion (no intermediary storage)
• No logs contain sensitive content
• Temporary files deleted after upload
• API calls use HTTPS encryption

Advanced Configuration

Environment Variables

export NOTION_API_KEY="secret_xxx"
export NOTION_DATABASE_ID="database-xxx"
export NOTION_WRITER_DEBUG=true

CLI Options

# Full options list
python scripts/write_to_notion.py --help

Common options:
  --content TEXT          Direct content to upload
  --file PATH            Path to markdown file
  --title TEXT           Page title (auto-generated if omitted)
  --database-id ID       Target database ID
  --parent-page-id ID    Parent page for nesting
  --tags TEXT            Comma-separated tags
  --template NAME        Template to use
  --auto-organize        Let AI organize content
  --smart-categorize     Auto-detect category
  --dry-run             Preview without uploading
  --verbose             Show detailed logs

Technical Architecture

┌─────────────────────────────────────────┐
│  User Input (text/file/directory)      │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│  Content Parser & Analyzer             │
│  - Markdown parsing                     │
│  - Structure detection                  │
│  - Content classification               │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│  AI Enhancement Layer                   │
│  - Smart formatting                     │
│  - Auto-tagging                         │
│  - Metadata generation                  │
│  - Template application                 │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│  Notion Block Converter                 │
│  - Markdown → Notion blocks             │
│  - Hierarchy building                   │
│  - Rich media handling                  │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│  Notion API Client                      │
│  - Rate limit handling                  │
│  - Error retry logic                    │
│  - Batch processing                     │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│  Notion Workspace                       │
│  - Beautifully formatted pages          │
└─────────────────────────────────────────┘

Contributing

Contributions welcome! Areas for improvement:

• Additional templates
• More conversion formats (Obsidian, Roam, etc.)
• Enhanced AI categorization
• Bi-directional sync
• Mobile app integration

License

MIT License - See LICENSE file for details

Quick Reference:

Setup: python scripts/setup.py Upload: python scripts/write_to_notion.py --content "text" Test: python scripts/test_connection.py Help: python scripts/write_to_notion.py --help