Outlook Calendar

Purpose

Manage Outlook Calendar events with the outlook-calendar companion CLI. The connector supports both personal Microsoft accounts and Microsoft 365 work or school accounts.

Tooling

Use exec to run the installed CLI directly from PATH.

outlook-calendar --status
outlook-calendar accounts
outlook-calendar disconnect
outlook-calendar list --page-size 10 [--time-min <RFC3339>] [--time-max <RFC3339>] [--query <text>] [--page-token <token>]
outlook-calendar get "<event_id>"
outlook-calendar create --summary "<title>" --start "<RFC3339-or-date>" --end "<RFC3339-or-date>" --timezone "<iana_tz>" [--attendee <email>] [--location <text>] [--description <text>] [--all-day]
outlook-calendar update "<event_id>" [--summary <title>] [--start <RFC3339>] [--end <RFC3339>] [--timezone <iana_tz>] [--location <text>] [--description <text>]
outlook-calendar delete "<event_id>"

Commands use the default linked calendar account unless --account <account_id> is provided. When the user clearly means a particular account, run outlook-calendar accounts, match its display_name, and pass its opaque account_id with --account. Ask when the match is ambiguous, and never silently retry against the default account. --account applies only to calendar operations; --status, accounts, and disconnect are connector-wide. To remove one calendar account while keeping the others, direct the user to that account under Connectors in Settings; do not run disconnect.

Once an account is selected, repeat the same --account <account_id> on every follow-up that uses results from that calendar, including pagination with --page-token, get, update, and delete. Event IDs and page tokens belong to the account that returned them.

For list, use --page-size for result count. --top, --limit, and --max-results are compatibility aliases only; do not use them in new commands. list uses --time-min / --time-max for time bounds. --start and --end are canonical only for create / update; list accepts them only as compatibility aliases.

JSON output contract:

• disconnect: parse ok, action, status, and disconnect_url.
• list: parse ok, count, next_page_token (when present, pass back as --page-token), retrieved_at, and events[] with fields such as id, summary, description, start, end, event_starts_at, event_ends_at, location, is_all_day, and attendees.
• get: parse ok, retrieved_at, and event.
• create / update: parse ok, action, event_id, and web_link.
• delete: parse ok, action, and event_id.

Auth

This skill uses the CLI-managed Outlook connector. Do not hand-write auth files.

First-use or reconnect flow:

1. Run outlook-calendar --status.
2. If the response includes connect_url, replace <connect_url> with the returned URL and share exactly this Markdown link: [Connect Outlook Calendar](<connect_url>); do not paste the raw URL separately. Wait for the user to finish linking.
3. Re-run the same status command before continuing.
4. If the response includes disconnect_url, the account is already connected.
5. If the connected response includes add_account_url, use it as [Add Outlook Calendar account](<add_account_url>) when another account should be linked.
6. If any command reports an auth failure, stop and run outlook-calendar --status. If it returns connect_url, share the normal connect link. Otherwise run outlook-calendar accounts: check the selected account when the failed command used --account, or every account when it did not. For each relevant row with needs_reauth: true, share the status response's add_account_url as [Reconnect Outlook Calendar account](<add_account_url>) and ask the user to sign in with that same Microsoft account. Never rerun a failed --account command without --account.

For disconnect requests, run outlook-calendar disconnect. When disconnect_url is present, replace <disconnect_url> with the returned URL and share exactly this Markdown link: [Disconnect Outlook Calendar](<disconnect_url>); do not paste the raw URL separately. If it is absent, say the account is already disconnected.

Operating Rules

1. Use list first when you need an event ID or when the user asks about a date range.
2. All timed values must be RFC3339 / ISO 8601. Use date-only values only with --all-day.
3. Always supply a valid IANA timezone on create, and on update whenever start or end times change.
4. Confirm with the user before creating an event that sends invitations.
5. Private event updates may proceed from a clear user request. The helper reads the current event before updating it; organizer-owned meetings with attendees require confirmation because Outlook sends meeting-update email.
6. The current helper does not support attendee changes on update. If the user asks to add or remove invitees on an existing event, explain that limitation instead of emitting an unsupported --attendee flag.
7. delete may proceed from a clear, unambiguous user request without an additional confirmation.
8. Event IDs are opaque Graph values. Reuse the exact id returned by list or get.
9. Never use the shared connector helper CLI for Outlook Calendar; status and linking must go through outlook-calendar --status.
10. Never surface raw Graph identifiers (event ids, calendar ids) or other internal response fields (change keys, page/skip tokens, raw JSON) in text shown to the user — including in summaries, lists, or per-item annotations. Reuse the ids only internally to chain follow-up commands (rule 8). The sole exceptions are when the user explicitly asks for a raw id or you must show one to troubleshoot a failure.
11. For timed events, prefer event_starts_at.user_local and event_ends_at.user_local; the raw Graph fields remain for compatibility. All-day values are calendar dates, not instants, and must not be timezone-shifted.

• Permission-withheld fields: a list result carrying a withheld entry had organizer and attendees removed by the user's "Access events" permission — the meeting is NOT guest-less. Answer from the remaining fields and mention that the permission hides the guest list. Only when the user actually needs a withheld field for one specific event and withheld.reason is requires_approval, read that event with get, which shows the user the approval prompt. Never get during routine browsing just to fill guest lists.