Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Notion workspace integration for searching, reading, and managing pages, databases, blocks, comments, users, and files. Also supports exporting Aurora RCA postmortems and action items to Notion databases.
Notion is a REMOTE service. Use ONLY the Notion tools listed below -- never shell commands or local file access.
Instructions
1. Discovery -- Always Start Here
Before any operation, search to understand the workspace layout:
notion_search(query='...', types=['page']) -- find pages by title keyword
notion_search(query='...', types=['database']) -- find databases by title keyword
notion_search(query='...', max_results=25) -- search all object types (pages + databases)
types accepts ["page"], ["database"], or omit for both.
max_results range: 1--100, default 10.
Returns: id, object type, title, url, last_edited_time for each result.
To read a specific page or database:
notion_fetch(url_or_id='<page_url_or_uuid>', max_length=5000) -- returns page body as markdown
Accepts full Notion URLs or bare UUIDs (with or without dashes).
Multiple sorts are applied in order (first sort is primary).
5. Users & People
notion_list_users(max_results=100, start_cursor=None) -- list all workspace members (people + bots).
notion_get_user(target_user_id) -- fetch a single user by ID.
notion_get_self() -- get the Aurora bot user (the integration itself).
notion_find_person(name_or_email) -- find a person:
Email (contains @): exact match.
Name: case-insensitive substring search across up to 20 pages of users.
Returns: found (bool), count, users array.
notion_list_teamspaces() -- best-effort listing of teamspaces (uses workspace search internally). Often empty on Free/Plus plans.
6. Comments
Post a comment:notion_create_comment(text, page_id=None, block_id=None, discussion_id=None)
Provide exactly ONE of: page_id (new top-level comment), block_id (comment on a block), discussion_id (reply to existing thread).
text: plain text (converted to rich_text internally). Supports inline formatting only (bold, italic, code, links) -- no block-level markdown.
Upload a file:notion_upload_file(file_path_or_url, filename=None, content_type=None)
Accepts local file path OR public https URL.
Auto-selects single-part (< 20 MB) or multi-part (10 MB chunks, up to 500 MB).
Content-type auto-detected if not provided.
Returns: upload_id (reference this when creating/updating pages), filename, size_bytes, status.
SSRF protection: URLs resolving to private/loopback IPs are blocked.
List uploads:notion_list_file_uploads(max_results=25, start_cursor=None) -- list recent file uploads by this integration.
8. Custom Emojis
notion_list_custom_emojis() -- list custom emojis in the workspace. Returns supported: false on plans without this feature.
9. Data Sources (Plan-Gated)
These endpoints require specific Notion plans. All return {"supported": false} gracefully on workspaces without access.
notion_create_data_source(payload) -- create a data source (full payload passed through).
notion_get_data_source(data_source_id) -- fetch by ID.
notion_update_data_source(data_source_id, updates) -- update attributes.
notion_update_data_source_properties(data_source_id, properties) -- update schema.
notion_query_data_source(data_source_id, filter=None, sorts=None, max_results=25, start_cursor=None) -- query with filter/sort/pagination.
notion_list_data_source_templates(data_source_id) -- list templates.
10. Database Views (Plan-Gated)
These endpoints require specific Notion plans. All return {"supported": false} gracefully on workspaces without access.
notion_create_view(payload) -- create a view on a database.
notion_update_view(view_id, updates) -- update filters, sorts, visible properties.
notion_delete_view(view_id) -- irreversible deletion of a view.
notion_list_database_views(database_id) -- list all views on a database.
notion_query_view(view_id, filter=None, sorts=None, max_results=25, start_cursor=None) -- query through a view.
11. RCA Postmortem Export (Aurora-Specific)
Export a postmortem:notion_export_postmortem(incident_id, database_id, action_items_database_id=None)
incident_id: UUID of the Aurora incident.
database_id: target Notion database for the postmortem page.
action_items_database_id: optional separate database for action items.
Creates a structured page with title "Postmortem -- Incident {id}", timeline, root cause, impact sections.
Auto-maps incident properties to database columns:
Parses unchecked markdown checkboxes from the postmortem body.
Creates one Notion database row per action item.
assignee_hints: optional map {"item_text_prefix": "user@email.com"} to assign owners.
Auto-detects title, people, and date properties in the target database schema.
Assignees resolved by email lookup against workspace users.
RCA Investigation Workflow
IMPORTANT: You MUST search Notion early in every RCA investigation. The workspace contains past postmortems, runbooks, and action items that provide critical historical context. Do NOT skip this step.
IMPORTANT: During RCA, Notion is READ-ONLY. Do NOT create pages, export postmortems, create action items, or write to Notion. The engineer reviews your findings and exports via the UI after approving.
Step 1 (EARLY -- do this within your first 3 tool calls) -- Search Notion for historical context:notion_search(query='<service_name>', types=['page']) to find past postmortems or runbooks related to the affected service.
Also try: notion_search(query='<alert_type_or_keyword>') for broader matches.
Step 3 -- Read relevant past postmortems:notion_fetch(url_or_id='<page_id>', max_length=10000) to get full postmortem content. Past incidents on the same service often reveal recurring root causes.
Important Rules
Notion is a REMOTE service. Use ONLY the Notion tools listed above -- never local commands.
All url_or_id / page_id / database_id parameters accept UUIDs with or without dashes.
notion_fetch truncates at max_length characters. For full content of long pages, paginate with notion_get_block_children.
Write operations (create, update, append, move, trash, delete) modify the user's live Notion workspace. Confirm destructive actions before executing.
notion_update_database_properties with a null value REMOVES a column and its data. Always confirm.
notion_delete_block is permanent and irreversible from the API.
notion_delete_view is irreversible.
Rich text content is capped at ~2000 characters per segment by Notion.
Pagination: all list/query endpoints return has_more (bool) and next_cursor (string). Pass start_cursor=next_cursor to fetch the next page.
Data sources, views, and custom emojis are plan-gated features. Tools return {"supported": false} on workspaces without access -- do not retry, inform the user.
Rate limiting: the Notion API enforces 3 requests/second. The client handles retries automatically (429 with Retry-After, 5xx with backoff). No manual throttling needed.
Auth errors: if a tool returns code: "reauth_required", ask the user to reconnect Notion at the connection page, then retry.
If a tool returns code: "not_connected", ask the user to connect Notion first.
