calendar

Calendar Skill

View agenda, create and manage events, check availability, and manage calendars using the gws CLI.

---

Auth Approach

Do NOT check authentication upfront. Just run the command. If it fails with an auth error (exit code 2), see the Self-Healing section for diagnostics.

---

Tool Preference

All operations use the gws CLI directly. No wrapper scripts.

• Helper commands (prefixed with +): Use for common operations. These handle timezone detection, formatting, and attendee management automatically.
• Raw API calls: Use when no helper exists. Pass parameters via --params '<JSON>' and request bodies via --json '<JSON>'. Resource paths are space-separated (e.g., gws calendar events list).

Always prefer + helpers when one exists for the operation.

---

Operations — Tier 1 (Read)

View Agenda

gws calendar +agenda
gws calendar +agenda --today
gws calendar +agenda --tomorrow
gws calendar +agenda --week
gws calendar +agenda --days 3
gws calendar +agenda --calendar 'Work'
gws calendar +agenda --today --timezone America/New_York

Get Event Details

gws calendar events get --params '{"calendarId": "primary", "eventId": "<id>"}'

List Events (Filtered)

gws calendar events list --params '{"calendarId": "primary", "timeMin": "<iso>", "timeMax": "<iso>"}'

Check Availability

gws calendar freebusy query --json '{"timeMin": "<iso>", "timeMax": "<iso>", "items": [{"id": "primary"}]}'

---

Operations — Tier 2 (Write)

Create Event

gws calendar +insert --summary '<title>' --start '<iso>' --end '<iso>'
gws calendar +insert --summary '<title>' --start '<iso>' --end '<iso>' --location '<place>'
gws calendar +insert --summary '<title>' --start '<iso>' --end '<iso>' --attendee alice@example.com --attendee bob@example.com
gws calendar +insert --summary '<title>' --start '<iso>' --end '<iso>' --meet
gws calendar +insert --summary '<title>' --start '<iso>' --end '<iso>' --description '<text>'

Quick-Add Event

gws calendar events quickAdd --params '{"calendarId": "primary", "text": "<natural language>"}'

Update Event

gws calendar events patch --params '{"calendarId": "primary", "eventId": "<id>"}' --json '<event-json>'

Move Event

gws calendar events move --params '{"calendarId": "primary", "eventId": "<id>", "destination": "<calId>"}'

---

Operations — Tier 3 (Manage)

Delete Event

gws calendar events delete --params '{"calendarId": "primary", "eventId": "<id>"}'

Confirm with the user before deleting.

List Calendars

gws calendar calendarList list

Create / Delete Calendar

gws calendar calendars insert --json '{"summary": "<name>"}'
gws calendar calendars delete --params '{"calendarId": "<id>"}'

Confirm with the user before deleting a calendar.

Access Control (ACL)

gws calendar acl list --params '{"calendarId": "<id>"}'
gws calendar acl insert --params '{"calendarId": "<id>"}' --json '{"role": "reader", "scope": {"type": "user", "value": "<email>"}}'
gws calendar acl delete --params '{"calendarId": "<id>", "ruleId": "<ruleId>"}'

---

Common Calendar Recipes

See calendar-recipes.md

---

Self-Healing

When a command fails:

Auth Errors (exit code 2)

Check if gws is available and authenticated:

which gws && gws auth status

If gws is not installed or not authenticated, tell the user:

"The gws CLI is not installed or not authenticated. Install and configure it: https://github.com/googleworkspace/cli"

Other Errors

• Check the command's help: gws calendar <command> --help
• Inspect the API schema: gws schema calendar.<resource>.<method>
• Use --dry-run to preview requests without executing
• Exit codes: 0=success, 1=API error, 2=auth error, 3=validation, 4=discovery, 5=internal
• Validation errors (exit 3): check --params JSON syntax and required fields

---

Behavioral Guidelines

• Prefer + helpers (+agenda, +insert) over raw API calls when available.
• Default to "calendarId": "primary" in --params unless the user specifies a different calendar.
• Use ISO 8601 / RFC 3339 format for all timestamps (e.g., 2026-03-18T14:00:00-04:00).
• Use --dry-run to preview commands before executing destructive operations.
• Confirm with the user before deleting events or calendars.
• When creating events with +insert, include timezone offset in the ISO timestamp.
• When the user asks "what's on my calendar" or "meetings today", use +agenda --today.
• When the user gives a natural-language event description, prefer quickAdd for simple cases and +insert for structured cases.