icalendar-sync - SKILL.md Agent Skill

name: icalendar-sync description: Secure iCloud Calendar operations for OpenClaw with CalDAV and macOS native bridge providers. Use when tasks require calendar listing, event retrieval, event creation, event updates (including recurring series modes), event deletion, or credential setup via keyring/environment/config file.

iCalendar Sync

Use this skill to perform iCloud calendar CRUD operations from OpenClaw agents.

1. Prepare Credentials Securely

Use App-Specific Passwords only (never the primary Apple ID password).

Prefer keyring storage:

python -m icalendar_sync setup --username user@icloud.com

Use non-interactive setup for automation:

export ICLOUD_USERNAME="user@icloud.com"
export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
python -m icalendar_sync setup --non-interactive

Use file storage only when keyring is unavailable (headless or GUI-restricted runtime):

python -m icalendar_sync setup --non-interactive --storage file --config ~/.openclaw/icalendar-sync.yaml

2. Choose Provider Deliberately

--provider auto: macOS uses native bridge, non-macOS uses CalDAV.
--provider caldav: force direct iCloud CalDAV.
--provider macos-native: force Calendar.app bridge (macOS only).

For CalDAV diagnostics, add:

--debug-http --user-agent "your-agent/1.0"

3. Execute Calendar Operations

List calendars:

python -m icalendar_sync list

Get events:

python -m icalendar_sync get --calendar "Personal" --days 7

Create event:

python -m icalendar_sync create --calendar "Personal" --json '{
  "summary": "Meeting",
  "dtstart": "2026-02-15T14:00:00+03:00",
  "dtend": "2026-02-15T15:00:00+03:00"
}'

Update event (simple):

python -m icalendar_sync update --calendar "Personal" --uid "event-uid" --json '{"summary":"Updated title"}'

Update recurring event instance:

python -m icalendar_sync update \
  --calendar "Work" \
  --uid "series-uid" \
  --recurrence-id "2026-03-01T09:00:00+03:00" \
  --mode single \
  --json '{"summary":"One-off change"}'

Modes for recurring updates:

single: update one instance (use --recurrence-id)
all: update whole series
future: split series and update this+future (use --recurrence-id)

Delete event:

python -m icalendar_sync delete --calendar "Personal" --uid "event-uid"

4. Input Contract

For create, require at least:

summary (string)
dtstart (ISO datetime)
dtend (ISO datetime, must be later than dtstart)

Optional fields:

description
location
status
priority (0-9)
alarms
rrule

5. Safety Rules

Validate calendar names; reject path-like payloads.
Keep credential material out of logs/output.
Prefer keyring over file storage.
If file storage is used, enforce strict file permissions (0600).

6. Failure Handling

If CalDAV auth/network fails on macOS and provider is auto/caldav, switch to macos-native and retry the same operation.

If JSON payload is supplied as file path, ensure file size stays within safe limits before parsing.