our-claude-skills/custom-skills/01-notion-organizer/code/CLAUDE.md

CLAUDE.md

Overview

Notion workspace management toolkit for database organization, schema migration, and bulk operations.

Quick Start

pip install -r scripts/requirements.txt

# Schema migration
python scripts/schema_migrator.py --source [DB_ID] --target [DB_ID] --dry-run

# Async bulk operations
python scripts/async_organizer.py --database [DB_ID] --action cleanup

Scripts

Script	Purpose
schema_migrator.py	Migrate data between databases with property mapping
async_organizer.py	Async bulk operations (cleanup, restructure, archive)

Schema Migrator

# Dry run (preview changes)
python scripts/schema_migrator.py \
  --source abc123 \
  --target def456 \
  --mapping mapping.json \
  --dry-run

# Execute migration
python scripts/schema_migrator.py \
  --source abc123 \
  --target def456 \
  --mapping mapping.json

Mapping File Format

{
  "properties": {
    "OldName": "NewName",
    "Status": "Status"
  },
  "transforms": {
    "Date": "date_to_iso"
  }
}

Async Organizer

# Cleanup empty/stale pages
python scripts/async_organizer.py --database [ID] --action cleanup

# Archive old pages
python scripts/async_organizer.py --database [ID] --action archive --days 90

# Restructure hierarchy
python scripts/async_organizer.py --database [ID] --action restructure

Rate Limits

Limit	Value
Requests/second	3 max
Items per request	100 max
Retry on 429	Exponential backoff

Configuration

Environment variables:

NOTION_TOKEN=secret_xxx

Notes

• Always use --dry-run first for destructive operations
• Large operations (1000+ pages) use async with progress reporting
• Scripts implement automatic rate limiting