Skill: ivangdavila/notion-calendar (version 1.0.0)

--- name: Notion Calendar slug: notion-calendar version: 1.0.0 homepage: https://clawic.com/skills/notion-calendar description: Manage Notion calendar databases with date-aware search, page creation, rescheduling, and safe workflows for planning views. changelog: "Initial release with date-aware Notion workflows, CLI fallback guidance, and safe create and reschedule patterns." metadata: {"clawdbot":{"emoji":"N","requires":{"env":["NOTION_API_KEY"],"config":["~/notion-calendar/"]},"primaryEnv":"NOTION_API_KEY","os":["linux","darwin","win32"],"configPaths":["~/notion-calendar/"]}} --- ## Setup On first use, read `setup.md` to establish token access, workspace scope, and safe write defaults. ## When to Use User wants to treat a Notion database as a calendar, editorial plan, launch schedule, content calendar, or dated task board. Agent handles schema discovery, time-window queries, page creation, rescheduling, and status updates for pages that appear in Notion calendar views. ## Requirements - `NOTION_API_KEY` for official API access. - A Notion integration shared with the target database. - Optional community CLI: `notion` from FroeMic/notion-cli for quick search and CRUD shortcuts. ## Architecture Memory lives in `~/notion-calendar/`. See `memory-template.md` for structure. ```text ~/notion-calendar/ |-- memory.md # Status, timezone defaults, and workspace context |-- calendars.md # Database and data source IDs plus property mappings |-- templates.md # Reusable page payload patterns `-- safety-log.md # Ambiguous matches, destructive confirmations, and rollbacks ``` ## Quick Reference | Topic | File | |-------|------| | Setup and first-run behavior | `setup.md` | | Memory structure | `memory-template.md` | | Calendar source mapping | `calendars.md` | | Reusable payload templates | `templates.md` | | Optional CLI patterns | `cli-patterns.md` | | Calendar database schema guidance | `calendar-schema.md` | | Query, create, and reschedule flows | `query-playbook.md` | | Common failures and fixes | `troubleshooting.md` | ## Core Rules ### 1. Treat Notion Calendar as Date-Driven Data Sources - The operational unit is a Notion database or data source with at least one date property. - Do not promise direct control of Google Calendar or native Notion Calendar app settings through this skill. ### 2. Discover Schema Before Writing - Retrieve the database container, then resolve the active `data_source_id` and property names before create or update operations. - Cache title, date, status, assignee, and timezone-relevant fields in `calendars.md` after user approval. ### 3. Use Explicit Time Windows - Convert requests such as "next week" or "this quarter" into bounded ISO dates with a declared timezone. - Query only the requested window first, then widen if the result set is empty or clearly incomplete. ### 4. Prefer the CLI for Fast Reads, Fallback to Official HTTP for Modern Gaps - If `notion` CLI is installed and the task is basic search, read, or simple page CRUD, use it for speed. - For `2025-09-03` data source workflows, schema migration, or any unsupported command, use direct requests to `api.notion.com`. ### 5. Read Before Write and Verify After - Before create, reschedule, archive, or status changes, fetch matching rows in the exact target window. - After a write, read back the changed page and report the final title, date, status, and URL. ### 6. Keep Calendar Semantics Explicit - Confirm whether a row is all-day, single timestamp, or start/end range before writing date values. - Recurrence is not a first-class calendar series here; if the user wants repeating items, create a template or batch future pages intentionally. ### 7. Escalate Ambiguity Instead of Guessing - If multiple pages share the same title, ask for the page URL, page ID, or the exact date window. - Never archive or move rows on a low-confidence title match. ## Common Traps - Assuming every database ID is enough on its own -> newer Notion versions may require `data_source_id`. - Writing to the first property named "Date" without schema review -> wrong calendar column updated. - Treating Notion rows as true recurring events -> repeat behavior must be modeled, not assumed. - Rescheduling by title only -> duplicate launch plans or editorial items get changed accidentally. - Querying wide open ranges by default -> noisy results and missed verification. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | `https://api.notion.com/v1/search` | Search text, filters, pagination cursor | Find candidate databases, data sources, or pages | | `https://api.notion.com/v1/databases/*` | Database ID | Retrieve container metadata and child data sources | | `https://api.notion.com/v1/data_sources/*` | Data source IDs, filters, sorts, property schema updates | Query rows and inspect or update calendar schema | | `https://api.notion.com/v1/pages/*` | Page properties and content updates | Create pages, reschedule items, update status | No other data is sent externally. ## Security & Privacy **Data that leaves your machine:** - Search text, page properties, dates, and page content sent to Notion through `api.notion.com`. **Data that stays local:** - Workspace context, property mappings, and safe defaults in `~/notion-calendar/`. **This skill does NOT:** - Store API keys in skill memory files. - Access undeclared third-party calendar APIs. - Claim a write succeeded without a read-back check. - Modify files outside `~/notion-calendar/` for this workflow. ## Scope This skill ONLY: - Works with Notion databases, data sources, and pages used as calendar items. - Uses the optional `notion` CLI when available for compatible operations. - Falls back to direct Notion API calls when the CLI lags the current API shape. This skill NEVER: - Configure Notion Calendar app preferences or account settings. - Synchronize Google Calendar accounts on the user's behalf. - Hide destructive changes behind implicit matches. ## Trust By using this skill, calendar-related workspace data is sent to Notion. Only install if you trust Notion with page titles, dates, status fields, and related planning metadata. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `api` - general REST API request patterns and debugging. - `dates` - precise date math, ranges, and timezone interpretation. - `pkm` - broader knowledge and workspace organization patterns. - `productivity` - execution systems around tasks and schedules. - `schedule` - planning logic when requests become multi-step scheduling work. ## Feedback - If useful: `clawhub star notion-calendar` - Stay updated: `clawhub sync`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)