refactor(skills): Restructure skills to dual-platform architecture
Major refactoring of ourdigital-custom-skills with new numbering system: ## Structure Changes - Each skill now has code/ (Claude Code) and desktop/ (Claude Desktop) versions - New progressive numbering: 01-09 General, 10-19 SEO, 20-29 GTM, 30-39 OurDigital, 40-49 Jamie ## Skill Reorganization - 01-notion-organizer (from 02) - 10-18: SEO tools split into focused skills (technical, on-page, local, schema, vitals, gsc, gateway) - 20-21: GTM audit and manager - 30-32: OurDigital designer, research, presentation - 40-41: Jamie brand editor and audit ## New Files - .claude/commands/: Slash command definitions for all skills - CLAUDE.md: Updated with new skill structure documentation - REFACTORING_PLAN.md: Migration documentation - COMPATIBILITY_REPORT.md, SKILLS_COMPARISON.md: Analysis docs ## Removed - Old skill directories (02-05, 10-14, 20-21 old numbering) - Consolidated into new structure with _archive/ for reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,250 @@
|
||||
# Notion Organizer Reference
|
||||
|
||||
## Notion API Fundamentals
|
||||
|
||||
### Base Configuration
|
||||
- **Base URL**: `https://api.notion.com`
|
||||
- **Current Version**: `2022-06-28`
|
||||
- **Authentication**: Bearer token in Authorization header
|
||||
|
||||
### Rate Limits
|
||||
|
||||
| Limit | Value | Strategy |
|
||||
|-------|-------|----------|
|
||||
| Requests/second | 3 (average) | Use throttling/semaphore |
|
||||
| Burst allowed | Small bursts | Implement exponential backoff |
|
||||
| Page size | 100 items max | Use pagination cursors |
|
||||
| Payload size | 500KB max | Split large operations |
|
||||
|
||||
### Core Object Hierarchy
|
||||
|
||||
```
|
||||
Workspace
|
||||
└── Database (container)
|
||||
└── Page (row)
|
||||
└── Block (content)
|
||||
```
|
||||
|
||||
### Property Types Reference
|
||||
|
||||
| Type | Use Case | Notes |
|
||||
|------|----------|-------|
|
||||
| `title` | Page name | Required, one per database |
|
||||
| `rich_text` | Text content | Max 2,000 chars |
|
||||
| `number` | Numeric values | Supports format options |
|
||||
| `select` | Single choice | Define options array |
|
||||
| `multi_select` | Multiple choices | Define options array |
|
||||
| `status` | Workflow states | Groups: To-do, In progress, Complete |
|
||||
| `date` | Dates/times | ISO 8601 format |
|
||||
| `checkbox` | Boolean | true/false |
|
||||
| `url` | Links | Max 2,000 chars |
|
||||
| `email` | Email addresses | Validation applied |
|
||||
| `phone_number` | Phone | String format |
|
||||
| `relation` | Links to pages | Requires database_id |
|
||||
| `rollup` | Aggregated data | Requires relation + function |
|
||||
| `formula` | Computed values | Expression syntax |
|
||||
| `files` | Attachments | External URLs or Notion hosted |
|
||||
| `people` | User references | Notion user IDs |
|
||||
| `created_time` | Auto timestamp | Read-only |
|
||||
| `created_by` | Auto user | Read-only |
|
||||
| `last_edited_time` | Auto timestamp | Read-only |
|
||||
| `last_edited_by` | Auto user | Read-only |
|
||||
|
||||
### Size Limits
|
||||
|
||||
| Element | Limit |
|
||||
|---------|-------|
|
||||
| Rich text content | 2,000 characters |
|
||||
| URL length | 2,000 characters |
|
||||
| Array elements | 100 items |
|
||||
| Page properties | 100 per page |
|
||||
| Database properties | 100 per database |
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Code | Status | Action |
|
||||
|------|--------|--------|
|
||||
| `rate_limited` | 429 | Wait Retry-After header seconds |
|
||||
| `validation_error` | 400 | Check request body format |
|
||||
| `object_not_found` | 404 | Verify sharing/permissions |
|
||||
| `unauthorized` | 401 | Check API token validity |
|
||||
| `conflict_error` | 409 | Resource was modified, refetch |
|
||||
| `internal_server_error` | 500 | Retry with backoff |
|
||||
|
||||
---
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Database Audit
|
||||
|
||||
**Purpose**: Analyze database structure and recommend optimizations
|
||||
|
||||
**Steps**:
|
||||
1. Fetch database schema via MCP or API
|
||||
2. Analyze property types, naming conventions, usage
|
||||
3. Identify issues:
|
||||
- Unused properties
|
||||
- Inconsistent naming
|
||||
- Suboptimal property types
|
||||
- Missing relations
|
||||
4. Present recommendations with rationale
|
||||
5. Execute approved changes incrementally
|
||||
|
||||
**Example Query**:
|
||||
```
|
||||
Audit my "Projects" database:
|
||||
- Check for unused properties
|
||||
- Identify naming inconsistencies
|
||||
- Recommend schema optimizations
|
||||
```
|
||||
|
||||
### Pattern 2: Bulk Reorganization
|
||||
|
||||
**Purpose**: Move/update many pages efficiently
|
||||
|
||||
**Decision Tree**:
|
||||
- ≤ 50 operations → Use MCP tools with staged execution
|
||||
- > 50 operations → Generate Python script
|
||||
|
||||
**Steps**:
|
||||
1. Assess scope (count affected pages)
|
||||
2. Estimate API calls and time
|
||||
3. Choose execution method (MCP vs Python)
|
||||
4. Execute with progress updates
|
||||
5. Generate summary report
|
||||
|
||||
**Example Query**:
|
||||
```
|
||||
Move all pages with status "Archived" from "Active Projects"
|
||||
to "Archive" database, preserving the Project Name and Date properties
|
||||
```
|
||||
|
||||
### Pattern 3: Schema Migration
|
||||
|
||||
**Purpose**: Transfer data between databases with different schemas
|
||||
|
||||
**Steps**:
|
||||
1. Fetch source database schema
|
||||
2. Fetch target database schema
|
||||
3. Create property mapping plan:
|
||||
- Direct mappings (same type)
|
||||
- Transformations needed (type conversion)
|
||||
- Unmappable properties (manual handling)
|
||||
4. Validate compatibility
|
||||
5. Execute migration:
|
||||
- MCP for small datasets
|
||||
- Python for large datasets
|
||||
6. Verify data integrity
|
||||
|
||||
**Property Mapping Template**:
|
||||
```
|
||||
Source Property → Target Property (Transformation)
|
||||
─────────────────────────────────────────────────
|
||||
Name (title) → Project Name (title) [Direct]
|
||||
Status (select) → Stage (status) [Map values]
|
||||
Due Date (date) → Deadline (date) [Direct]
|
||||
Tags (multi) → Categories (multi) [Merge options]
|
||||
Notes (text) → Description (text) [Direct]
|
||||
Owner (text) → Assignee (people) [Manual]
|
||||
```
|
||||
|
||||
### Pattern 4: Property Cleanup
|
||||
|
||||
**Purpose**: Standardize properties across databases
|
||||
|
||||
**Common Tasks**:
|
||||
- Rename properties to consistent convention (camelCase, snake_case, Title Case)
|
||||
- Consolidate duplicate select/multi-select options
|
||||
- Remove unused properties
|
||||
- Add missing required properties
|
||||
|
||||
**Naming Convention Guide**:
|
||||
```
|
||||
Recommended: Title Case with spaces
|
||||
Examples: "Project Name", "Due Date", "Status", "Assigned To"
|
||||
|
||||
Alternative: camelCase (for technical databases)
|
||||
Examples: "projectName", "dueDate", "status", "assignedTo"
|
||||
```
|
||||
|
||||
### Pattern 5: Duplicate Detection
|
||||
|
||||
**Purpose**: Find and handle duplicate or similar content
|
||||
|
||||
**Detection Strategies**:
|
||||
1. Exact title match
|
||||
2. Fuzzy title similarity (Levenshtein distance)
|
||||
3. Property combination match (e.g., same name + date)
|
||||
4. Content hash comparison
|
||||
|
||||
**Resolution Options**:
|
||||
- Merge: Combine properties from duplicates
|
||||
- Archive: Move older duplicate to archive
|
||||
- Delete: Remove with user confirmation
|
||||
- Link: Create relation between related items
|
||||
|
||||
---
|
||||
|
||||
## MCP Tool Usage Examples
|
||||
|
||||
### Search for Pages
|
||||
```
|
||||
Use mcp__notion__search to find:
|
||||
- Query: "marketing campaign"
|
||||
- Filter: database_id = "abc123"
|
||||
```
|
||||
|
||||
### Query Database with Filters
|
||||
```
|
||||
Use mcp__notion__query-database:
|
||||
- Database ID: "abc123"
|
||||
- Filter: { "property": "Status", "select": { "equals": "Active" } }
|
||||
- Sorts: [{ "property": "Created", "direction": "descending" }]
|
||||
```
|
||||
|
||||
### Update Page Properties
|
||||
```
|
||||
Use mcp__notion__update-page:
|
||||
- Page ID: "xyz789"
|
||||
- Properties: {
|
||||
"Status": { "select": { "name": "Completed" } },
|
||||
"Completed Date": { "date": { "start": "2025-12-05" } }
|
||||
}
|
||||
```
|
||||
|
||||
### Create New Page
|
||||
```
|
||||
Use mcp__notion__create-page:
|
||||
- Parent: { "database_id": "abc123" }
|
||||
- Properties: {
|
||||
"Name": { "title": [{ "text": { "content": "New Project" } }] },
|
||||
"Status": { "select": { "name": "Planning" } }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Fetch Before Modify
|
||||
Never assume database structure. Always retrieve current schema first.
|
||||
|
||||
### 2. Batch Operations Wisely
|
||||
- Group related updates
|
||||
- Use pagination for queries
|
||||
- Implement checkpoints for large operations
|
||||
|
||||
### 3. Handle Relations Carefully
|
||||
- Relations require both databases to be accessible
|
||||
- Synced databases need special handling
|
||||
- Rollups depend on relations - update order matters
|
||||
|
||||
### 4. Preserve Data Integrity
|
||||
- Back up critical data before major changes
|
||||
- Use transactions where possible
|
||||
- Verify changes after execution
|
||||
|
||||
### 5. Respect User Permissions
|
||||
- Check integration has access to target resources
|
||||
- Request additional permissions when needed
|
||||
- Document permission requirements
|
||||
Reference in New Issue
Block a user