refactor: Reorganize skill numbering and update documentation
Skill Numbering Changes: - 01-03: OurDigital core (was 30-32) - 31-32: Notion tools (was 01-02) - 99_archive: Renamed from _archive for sorting New Files: - AGENTS.md: Claude Code agent routing guide - requirements.txt for 00-claude-code-setting, 32-notion-writer, 43-jamie-youtube-manager Documentation Updates: - CLAUDE.md: Updated skill inventory (23 skills) - AUDIT_REPORT.md: Current completion status (91%) - Archived REFACTORING_PLAN.md (most tasks complete) Removed: - ga-agent-skills/ (moved to separate repo ~/Project/dintel-ga4-agent) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
233
custom-skills/32-notion-writer/code/CLAUDE.md
Normal file
233
custom-skills/32-notion-writer/code/CLAUDE.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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](https://www.notion.so/my-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
|
||||
|
||||
```bash
|
||||
cd ~/Project/claude-skills/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
|
||||
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Test Connection
|
||||
|
||||
```bash
|
||||
python notion_writer.py --test
|
||||
```
|
||||
|
||||
### Get Page/Database Info
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```markdown
|
||||
```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
|
||||
|
||||
```bash
|
||||
python notion_writer.py \
|
||||
--database "https://notion.so/Meeting-Notes-abc123" \
|
||||
--title "Weekly Standup - Dec 26" \
|
||||
--file meeting_notes.md
|
||||
```
|
||||
|
||||
### Pipe from Another Tool
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Navigate
|
||||
cd ~/Project/claude-skills/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*
|
||||
Reference in New Issue
Block a user