# Notion Writer

> AI-powered note organizer that structures and uploads user notes to Notion. Automatically formats content, creates proper hierarchy, and maintains clean documentation with guided API setup.

- Skill: `teamily-ai/notion-writer` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add teamily-ai/notion-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/teamily-ai/notion-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: teamily-ai (https://skillmd.com/u/teamily-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/teamily-ai/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:**

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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:**
```bash
# Upload entire directory of notes
python scripts/batch_upload.py \
  --directory "./meeting_notes" \
  --template meeting \
  --auto-organize \
  --tags "meetings,2026"
```

**Template Usage:**
```bash
# 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:**
```bash
# Let AI decide best organization
python scripts/write_to_notion.py \
  --file "notes.md" \
  --auto-organize \
  --smart-categorize
```

## Environment Setup

### 1. Install Dependencies

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

### 2. Interactive Setup (Guides User Through API Configuration)

```bash
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`:

```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

```bash
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):**
```bash
python scripts/list_databases.py
```
This will list all databases your integration can access.

### Step 4: Configure the Skill

Run the interactive setup:
```bash
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**
```markdown
# 📅 [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**
```markdown
# 📋 [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**
```markdown
# 📔 [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

```bash
# 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

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

### CLI Options

```bash
# 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`