home / skills / openclaw / skills / icalendar-sync

icalendar-sync skill

This skill securely manages iCloud calendars via CalDAV or macOS bridge, enabling listing, creating, updating, and deleting events with safe credentials.

npx playbooks add skill openclaw/skills --skill icalendar-sync

Review the files below or copy the command above to add this skill to your agents.

Files (20)

SKILL.md

3.1 KB

---
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:

```bash
python -m icalendar_sync setup --username [email protected]
```

Use non-interactive setup for automation:

```bash
export ICLOUD_USERNAME="[email protected]"
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):

```bash
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:

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

## 3. Execute Calendar Operations

List calendars:

```bash
python -m icalendar_sync list
```

Get events:

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

Create event:

```bash
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):

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

Update recurring event instance:

```bash
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:

```bash
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.

Overview

This skill provides secure iCloud Calendar operations for OpenClaw agents, supporting both CalDAV and a macOS native bridge. It enables listing calendars, retrieving events, creating and updating events (including recurring series modes), deleting events, and secure credential setup. The implementation favors keyring-backed credentials and safe defaults for automation and headless environments.

How this skill works

The skill authenticates to iCloud using app-specific passwords stored in the system keyring, environment variables, or a protected config file when necessary. It selects a provider automatically (macOS native bridge on macOS, CalDAV elsewhere) or allows forcing a specific provider. Commands accept JSON payloads for event create/update and provide recurrence-aware operations with modes for single, all, or future-instance updates. The skill enforces input validation, credential safety, and retry behavior when provider or network errors occur.

When to use it

Automated agents need to list calendars or fetch upcoming events from an iCloud account.
Creating or updating single events or recurring series from a programmatic workflow.
Deleting events or managing calendar items as part of a scheduled task or sync.
Setting up credentials non-interactively for CI/CD or headless deployments.
Running on macOS where the native Calendar.app bridge improves reliability.

Best practices

Always use an app-specific password; never store the primary Apple ID password.
Prefer keyring storage for credentials; use file storage only when keyring is unavailable and enforce 0600 permissions.
Validate calendar names and reject path-like or suspicious payload fields before performing operations.
Avoid logging credential material or full JSON payloads that contain secrets.
When using CalDAV add debug flags selectively (debug-http, custom user-agent) and switch to macOS native provider on auth/network failures.

Example use cases

Agent lists calendars and syncs upcoming 7 days of events into a corporate dashboard.
Create a meeting event with summary, start/end ISO datetimes, location and alarms via a JSON payload.
Update one instance of a recurring meeting (mode: single) without altering the rest of the series.
Non-interactive credential setup in CI using environment variables for automated deployments.
Delete canceled events across a personal calendar as part of a cleanup routine.

FAQ

Can I run this on macOS and non-macOS systems?

Yes. The provider auto mode uses a macOS native bridge on macOS and CalDAV on other platforms; you can also force either provider.

What credentials are required?

An iCloud username and an app-specific password. Store them in the keyring, environment variables, or a protected config file (file storage is a fallback).

How do I update a single instance of a recurring event?

Use the update command with --recurrence-id and --mode single to target one occurrence without changing the series.