macOS Calendar & Reminders Management

This skill guides you through effective use of che-ical-mcp for calendar and task management on macOS.

Date/Time Format

CRITICAL: Always use ISO8601 format with timezone for all date/time parameters:

2026-01-18T14:00:00+08:00  (correct)
2026-01-18 14:00           (wrong - will fail)

Use the user's local timezone. For Taiwan: +08:00. An event module's events follow the module (a conference's sessions use the conference's zone; its all-day umbrella takes date-only values).

Tool Categories

1. Discovery (Start Here)

Before creating or modifying, always check existing state:

list_calendars          → See all calendars and their sources
list_events_quick       → Quick view: "today", "this_week", "next_7_days"
list_reminders          → See tasks by list or completion status

2. Events (Calendar)

Week Start Day (v0.8.2+): For this_week/next_week ranges, use week_starts_on:

• system (default): Use system locale
• monday: ISO 8601 (Europe, Asia)
• sunday: US, Japan
• saturday: Middle East

3. Reminders (Tasks)

Every boolean argument on every tool (all_day, clear_*, include_completed, dry_run, delete_original, …) is a strict JSON boolean (#207): strings and numbers are rejected; omit or null keeps the default.

Recurring reminders (#194): list/search items carry has_recurrence, recurrence_rules and a due object (date / time / timezone / date_time). complete_reminder returns operation (write outcome), observed (the saved object) and next_occurrence. Read `operation.status`, not `is_completed`: completing a recurring reminder advances the same item to its next occurrence, so is_completed can be false after a successful write. next_occurrence.status: "confirmed" carries the next due (also in the message); "unknown" is not a failure — never repeat the write because of it.

4. Batch Operations (Efficiency)

Common Workflows

Schedule a Meeting

If the input matches a module's trigger in rules/event-modules.md (today: a conference program or a booking for a stay) and that module is on, build it as the module says instead of the steps below for what the module handles (a program, a stay); other items in the same message, such as a flight, still go through the steps below; otherwise carry on below.

1. Resolve calendar_name  → name from the user, else the folder's calendar_routing rules (rules/calendar-routing.md), else ask
2. check_conflicts(start_time, end_time)  → Ensure no overlap
3. create_event(title, start_time, end_time, calendar_name, location?, alarms_minutes_offsets?)
4. Report how the calendar was decided (the `Routed to …` / `Not routed: …` line)

Recurring Series with Excluded Dates (#182)

Skip specific dates (e.g. holidays) when creating a recurring event, via recurrence.excluded_occurrence_dates:

create_event({
  "title": "Weekly seminar",
  "start_time": "2026-09-07T14:00:00+08:00",
  "end_time": "2026-09-07T16:00:00+08:00",
  "calendar_name": "Work",
  "recurrence": {
    "frequency": "weekly",
    "excluded_occurrence_dates": ["2026-09-28", "2026-10-05"]
  }
})

• Same date grammar as occurrence_date; date-only values are interpreted in the event timezone. Max 100, duplicates rejected.
• Applied with best-effort all-or-nothing semantics: if any exclusion fails, the entire new series is removed via compensating delete (rollback failure is reported, never silent). The first occurrence cannot be excluded. One undo removes the whole series including exclusions.
• Response includes excluded_occurrence_dates (normalized yyyy-MM-dd) + exclusion_count. Also available per-item in create_events_batch (reported per-item).
• update_event and create_reminder reject this field — it is creation-time only.

Weekly Review

1. list_events_quick(range: "this_week")  → See upcoming events
2. list_reminders(completed: false)       → See pending tasks
3. search_events(keywords: ["important"]) → Find priority items

Calendar Migration

1. list_calendars()                       → Identify source/target
2. find_duplicate_events(calendars, date_range)  → Check for duplicates
3. move_events_batch(event_ids, target_calendar) → Move events

Source Disambiguation

When multiple calendars have the same name (e.g., "Work" in both iCloud and Google):

create_event(
  calendar_name: "Work",
  calendar_source: "iCloud",  ← Specify the source
  ...
)

Available sources: "iCloud", "Google", "Exchange", "CalDAV", "Local"

Best Practices

1. Always specify calendar_name for create operations (v0.8.0+) — resolve it through rules/calendar-routing.md first; ask only when no rule applies
2. Use batch operations for multiple similar actions
3. Check conflicts before scheduling important events
4. Use search instead of listing all events when looking for specific items
5. Prefer list_events_quick over list_events for common ranges
6. Specify week_starts_on when user's locale differs from expected (v0.8.2+)