our-claude-skills/custom-skills/02-notion-writer/code/CLAUDE.md

Notion Writer - Claude Code Skill

Purpose: Push markdown content to Notion pages or databases Platform: Claude Code (CLI) Input: Markdown files, Notion URLs Output: Content written to Notion

---

Capabilities

Feature	Input	Output
Page Content Append	Markdown + Page URL	Appended blocks
Page Content Replace	Markdown + Page URL	Replaced content
Database Row Create	Markdown + DB URL + Title	New database row
Connection Test	API token	Connection status
Page/DB Info	URL	Metadata

---

Setup

1. Create Notion Integration

1. Go to Notion Integrations
2. Click "New integration"
3. Name it (e.g., "Claude Writer")
4. Select workspace
5. Copy the "Internal Integration Token"

2. Share Pages/Databases with Integration

Important: You must share each page or database with your integration:

1. Open the Notion page/database
2. Click "..." menu → "Connections"
3. Add your integration

3. Configure Environment

cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts

# Create .env from example
cp .env.example .env

# Edit and add your token
nano .env

.env file:

NOTION_API_KEY=secret_your_integration_token

4. Activate Environment

source venv/bin/activate

---

Usage

Test Connection

python notion_writer.py --test

Get Page/Database Info

# Page info
python notion_writer.py --page "https://notion.so/My-Page-abc123" --info

# Database info
python notion_writer.py --database "https://notion.so/abc123" --info

Write to Page

# Append content to page
python notion_writer.py --page PAGE_URL --file content.md

# Replace page content
python notion_writer.py --page PAGE_URL --file content.md --replace

# From stdin
cat report.md | python notion_writer.py --page PAGE_URL --stdin

Create Database Row

# Create row with title and content
python notion_writer.py --database DB_URL --title "New Entry" --file content.md

# Title only
python notion_writer.py --database DB_URL --title "Empty Entry"

---

Markdown Support

Supported Elements

Markdown	Notion Block
# Heading	Heading 1
## Heading	Heading 2
### Heading	Heading 3
- item	Bulleted list
1. item	Numbered list
- [ ] task	To-do (unchecked)
- [x] task	To-do (checked)
> quote	Quote
```code```	Code block
---	Divider
Paragraphs	Paragraph

Code Block Languages

Specify language after opening backticks:

```python
print("Hello")

---

## Examples

### Push SEO Audit Report

```bash
python notion_writer.py \
  --page "https://notion.so/SEO-Reports-abc123" \
  --file ~/reports/seo_audit_2025.md

Create Meeting Notes Entry

python notion_writer.py \
  --database "https://notion.so/Meeting-Notes-abc123" \
  --title "Weekly Standup - Dec 26" \
  --file meeting_notes.md

Pipe from Another Tool

# Pipe YouTube video info to Notion
python jamie_video_info.py VIDEO_ID --json | \
  python notion_writer.py --page PAGE_URL --stdin

---

API Limits

Limit	Value
Blocks per request	100
Text content per block	2,000 chars
Requests per second	~3

The script automatically batches large content.

---

Troubleshooting

"Could not find page"

• Ensure page is shared with your integration
• Check URL/ID is correct

"Invalid token"

• Verify NOTION_API_KEY in .env
• Token should start with secret_

"Rate limited"

• Wait and retry
• Script handles batching but rapid calls may hit limits

---

File Structure

02-notion-writer/
├── code/
│   ├── CLAUDE.md              # This skill document
│   ├── scripts/
│   │   ├── notion_writer.py   # Main script
│   │   ├── venv/              # Python environment
│   │   ├── .env               # API token (not committed)
│   │   └── .env.example       # Template
│   ├── output/                # For generated content
│   └── references/
└── desktop/                   # Claude Desktop version (future)

---

Quick Reference

# Navigate
cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts
source venv/bin/activate

# Test
python notion_writer.py --test

# Write to page
python notion_writer.py -p PAGE_URL -f content.md

# Replace content
python notion_writer.py -p PAGE_URL -f content.md -r

# Create DB row
python notion_writer.py -d DB_URL -t "Title" -f content.md

---

Version 1.0.0 | Claude Code | 2025-12-26