directory changes and restructuring
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
95
custom-skills/01-notion-organizer/desktop/SKILL.md
Normal file
95
custom-skills/01-notion-organizer/desktop/SKILL.md
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: notion-organizer
|
||||
version: 1.0.0
|
||||
description: Notion workspace management agent for organizing, restructuring, consolidating, and maintaining databases and pages. Use when user asks to search Notion, organize databases, clean up properties, migrate data, merge databases, audit schemas, or manage Notion content. Activates for keywords like Notion, database, knowledge base, wiki, workspace organization.
|
||||
allowed-tools: mcp__notion__*, Read, Write, Edit, Bash(python:*), Bash(pip:*)
|
||||
---
|
||||
|
||||
# Notion Organizer Skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Specialized Notion workspace management capability for:
|
||||
- Database schema analysis and optimization
|
||||
- Property standardization and cleanup
|
||||
- Content restructuring and hierarchy optimization
|
||||
- Database merging and migration
|
||||
- Bulk operations with rate-limit compliance
|
||||
|
||||
## Execution Strategy: Three-Tier Approach
|
||||
|
||||
Always follow this priority order:
|
||||
|
||||
### Tier 1: Notion MCP Tools (Primary)
|
||||
|
||||
Use built-in MCP tools first. Available tools:
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `mcp__notion__search` | Find pages/databases by keyword |
|
||||
| `mcp__notion__get-page` | Retrieve page content |
|
||||
| `mcp__notion__get-database` | Retrieve database schema |
|
||||
| `mcp__notion__create-page` | Create new pages |
|
||||
| `mcp__notion__update-page` | Modify page properties |
|
||||
| `mcp__notion__query-database` | Query database with filters |
|
||||
|
||||
### Tier 2: Alternative Approaches (Fallback)
|
||||
|
||||
If MCP tools insufficient:
|
||||
- Export/import via filesystem (user action required)
|
||||
- Memory tools for tracking state across sessions
|
||||
- Sequential thinking for complex planning
|
||||
|
||||
### Tier 3: Python Scripts (Advanced)
|
||||
|
||||
For bulk operations (50+ items):
|
||||
- Generate async Python scripts
|
||||
- Include rate limiting (3 req/sec max)
|
||||
- Provide requirements.txt
|
||||
- Always include dry-run option
|
||||
|
||||
See `scripts/` directory for templates.
|
||||
|
||||
## Operational Guidelines
|
||||
|
||||
### Before Any Modification
|
||||
1. **Fetch first**: Always examine current structure before changes
|
||||
2. **Confirm destructive actions**: Get user approval for deletes/major restructures
|
||||
3. **Estimate impact**: For large operations, provide time/API call estimates
|
||||
4. **Backup reminder**: Remind about Notion version history
|
||||
|
||||
### Rate Limits (Critical)
|
||||
- Maximum: 3 requests/second average
|
||||
- Use pagination (100 items max per request)
|
||||
- Implement exponential backoff on 429 errors
|
||||
|
||||
### Communication
|
||||
- Korean for explanations (한국어로 설명)
|
||||
- English for code and technical terms
|
||||
- Structured before/after summaries
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Database Audit
|
||||
"Analyze [database name] structure and recommend optimizations"
|
||||
|
||||
### Property Cleanup
|
||||
"Standardize property names in [database] to [convention]"
|
||||
|
||||
### Bulk Move
|
||||
"Move all pages tagged [X] from [source] to [target]"
|
||||
|
||||
### Schema Migration
|
||||
"Migrate data from [source database] to [target database]"
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
See `reference.md` for detailed workflow documentation.
|
||||
See `scripts/` for Python templates.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Cannot access unshared databases/pages
|
||||
- Cannot modify workspace settings
|
||||
- Cannot recover permanently deleted content
|
||||
- Large operations (1000+ pages) require Python scripts
|
||||
299
custom-skills/01-notion-organizer/desktop/examples/examples.md
Normal file
299
custom-skills/01-notion-organizer/desktop/examples/examples.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Notion Organizer Examples
|
||||
|
||||
## Quick Reference: Common Tasks
|
||||
|
||||
### 1. Database Audit
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Audit my "Client Projects" database and recommend optimizations
|
||||
```
|
||||
|
||||
**Expected Actions:**
|
||||
1. Fetch database schema using MCP
|
||||
2. Analyze properties: types, naming, usage
|
||||
3. Report findings in Korean
|
||||
4. Recommend specific improvements
|
||||
|
||||
**Sample Output:**
|
||||
```
|
||||
## Database Audit: Client Projects
|
||||
|
||||
### 현재 구조 (Current Structure)
|
||||
- Properties: 15개
|
||||
- 페이지 수: 234개
|
||||
|
||||
### 발견된 문제점 (Issues Found)
|
||||
|
||||
1. **중복 속성**: "담당자"와 "Assignee" 동일한 용도
|
||||
2. **미사용 속성**: "Legacy ID" - 모든 값이 비어있음
|
||||
3. **명명 불일치**: "due_date" vs "Due Date" vs "마감일"
|
||||
|
||||
### 권장 조치 (Recommendations)
|
||||
|
||||
1. "담당자"와 "Assignee" 통합 → "담당자"로 유지
|
||||
2. "Legacy ID" 속성 삭제
|
||||
3. 명명 규칙 통일: Title Case 권장
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Bulk Status Update
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Change all pages with status "Pending Review" to "In Review"
|
||||
in the Tasks database
|
||||
```
|
||||
|
||||
**Tier 1 Approach (MCP):**
|
||||
```python
|
||||
# Claude uses MCP tools:
|
||||
1. mcp__notion__query-database with filter:
|
||||
{"property": "Status", "select": {"equals": "Pending Review"}}
|
||||
|
||||
2. For each page, mcp__notion__update-page:
|
||||
{"Status": {"select": {"name": "In Review"}}}
|
||||
```
|
||||
|
||||
**Tier 3 Approach (Python - for 50+ pages):**
|
||||
```bash
|
||||
python scripts/async_organizer.py \
|
||||
--database-id abc123 \
|
||||
--operation status-update \
|
||||
--old-status "Pending Review" \
|
||||
--new-status "In Review" \
|
||||
--dry-run # Test first!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Schema Migration
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Migrate data from "Old Projects" to "New Projects" database.
|
||||
Map Status→Stage, Due Date→Deadline, Tags→Categories
|
||||
```
|
||||
|
||||
**Step 1: Generate Mapping Template**
|
||||
```bash
|
||||
python scripts/schema_migrator.py \
|
||||
--source-db old_projects_id \
|
||||
--target-db new_projects_id \
|
||||
--generate-mapping \
|
||||
--output my_mapping.json
|
||||
```
|
||||
|
||||
**Step 2: Customize Mapping**
|
||||
Edit `my_mapping.json`:
|
||||
```json
|
||||
{
|
||||
"Status": {
|
||||
"target": "Stage",
|
||||
"value_mapping": {
|
||||
"Todo": "Backlog",
|
||||
"Doing": "In Progress",
|
||||
"Done": "Complete"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Execute Migration**
|
||||
```bash
|
||||
# Dry run first
|
||||
python scripts/schema_migrator.py \
|
||||
--source-db old_projects_id \
|
||||
--target-db new_projects_id \
|
||||
--mapping my_mapping.json \
|
||||
--dry-run
|
||||
|
||||
# Execute
|
||||
python scripts/schema_migrator.py \
|
||||
--source-db old_projects_id \
|
||||
--target-db new_projects_id \
|
||||
--mapping my_mapping.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Property Cleanup
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Standardize all property names in "Marketing Campaigns"
|
||||
to Title Case with spaces
|
||||
```
|
||||
|
||||
**Before:**
|
||||
```
|
||||
- campaign_name → Campaign Name
|
||||
- startDate → Start Date
|
||||
- end-date → End Date
|
||||
- STATUS → Status
|
||||
- assigned_to → Assigned To
|
||||
```
|
||||
|
||||
**MCP Approach:**
|
||||
```
|
||||
Use mcp__notion__update-database to rename properties:
|
||||
{
|
||||
"properties": {
|
||||
"campaign_name": { "name": "Campaign Name" },
|
||||
"startDate": { "name": "Start Date" },
|
||||
"end-date": { "name": "End Date" },
|
||||
"STATUS": { "name": "Status" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Duplicate Detection
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Find duplicate entries in "Contacts" database based on email
|
||||
```
|
||||
|
||||
**Python Script Approach:**
|
||||
```python
|
||||
# Pseudocode for duplicate detection
|
||||
pages = fetch_all_pages(database_id)
|
||||
|
||||
# Group by email
|
||||
email_groups = {}
|
||||
for page in pages:
|
||||
email = get_property(page, "Email")
|
||||
if email:
|
||||
email_groups.setdefault(email, []).append(page)
|
||||
|
||||
# Find duplicates
|
||||
duplicates = {
|
||||
email: pages
|
||||
for email, pages in email_groups.items()
|
||||
if len(pages) > 1
|
||||
}
|
||||
|
||||
# Report
|
||||
for email, dup_pages in duplicates.items():
|
||||
print(f"Duplicate: {email}")
|
||||
for p in dup_pages:
|
||||
print(f" - {get_title(p)} (created: {p['created_time']})")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Archive Old Content
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Move all tasks completed more than 90 days ago to Archive database
|
||||
```
|
||||
|
||||
**Filter:**
|
||||
```json
|
||||
{
|
||||
"and": [
|
||||
{
|
||||
"property": "Status",
|
||||
"status": { "equals": "Complete" }
|
||||
},
|
||||
{
|
||||
"property": "Completed Date",
|
||||
"date": {
|
||||
"before": "2025-09-07"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Process:**
|
||||
1. Query with filter
|
||||
2. For each page:
|
||||
- Create copy in Archive database
|
||||
- Update original with "Archived" status or delete
|
||||
3. Report summary
|
||||
|
||||
---
|
||||
|
||||
### 7. Relation Audit
|
||||
|
||||
**Request:**
|
||||
```
|
||||
Find all pages in "Tasks" that have broken relations to "Projects"
|
||||
```
|
||||
|
||||
**Approach:**
|
||||
1. Fetch all Tasks pages
|
||||
2. For each task, check Project relation
|
||||
3. Verify referenced Project page exists
|
||||
4. Report broken relations
|
||||
|
||||
**Sample Output:**
|
||||
```
|
||||
## Relation Audit: Tasks → Projects
|
||||
|
||||
총 작업: 150개
|
||||
정상 연결: 142개
|
||||
끊어진 연결: 8개
|
||||
|
||||
### 끊어진 연결 목록:
|
||||
1. "Website Redesign Phase 2" → Project not found
|
||||
2. "Q3 Marketing Review" → Project deleted
|
||||
...
|
||||
|
||||
### 권장 조치:
|
||||
- 삭제된 프로젝트 복원 또는
|
||||
- 해당 작업들을 다른 프로젝트에 재할당
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
### Quick Start
|
||||
```bash
|
||||
# Navigate to scripts directory
|
||||
cd ~/.claude/skills/notion-organizer/scripts
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # macOS/Linux
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Set environment variable
|
||||
export NOTION_TOKEN="your_token_here"
|
||||
# Or create .env file with NOTION_TOKEN=your_token
|
||||
```
|
||||
|
||||
### Verify Setup
|
||||
```bash
|
||||
# Test with audit (read-only)
|
||||
python async_organizer.py --database-id YOUR_DB_ID --operation audit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Rate Limit Errors (429)
|
||||
- Scripts automatically retry with exponential backoff
|
||||
- If persistent, reduce `MAX_CONCURRENT_REQUESTS` to 2
|
||||
|
||||
### Permission Errors (404)
|
||||
- Ensure database is shared with your integration
|
||||
- Check integration has correct capabilities
|
||||
|
||||
### Property Type Mismatch
|
||||
- Use `--generate-mapping` to see current types
|
||||
- Some conversions require manual handling (e.g., people → text)
|
||||
|
||||
### Large Databases (1000+ pages)
|
||||
- Always use Python scripts, not MCP
|
||||
- Consider running in batches with checkpoints
|
||||
- Monitor API usage in Notion settings
|
||||
Reference in New Issue
Block a user