Google Calendar

Google Calendar Skill

Overview

This skill provides full Google Calendar functionality through gcalcli. You can read, create, edit, delete, search, and manage calendar events — everything Google Calendar can do, you can do here.

Capabilities

• View agenda and upcoming events
• Add new events (with title, time, location, description, attendees, reminders)
• Quick-add events using natural language
• Edit existing events
• Delete events
• Search for events by keyword
• Check for scheduling conflicts
• View weekly/monthly calendar layouts
• Import .ics files
• List all calendars

---

Reading Events

Step 1: Check Sync Freshness

Before answering any calendar question, read ~/.kiro/calendar/events.json and check the last_sync field:

• Fresh ( 6 hours): Run sync first

Step 2: Read Calendar Data

Read ~/.kiro/calendar/events.json. Structure:

{
  "last_sync": "2026-02-11T18:47:35",
  "timezone": "Asia/Taipei",
  "events": [
    {
      "start_date": "2026-02-11",
      "start_time": "09:00",
      "end_date": "2026-02-11",
      "end_time": "10:00",
      "title": "Team Standup",
      "location": "Zoom",
      "calendar": "Work"
    }
  ]
}

Step 3: Answer the Question

• Today's schedule: Filter by today's date
• This week: Filter by current week
• Availability: Look for gaps between events
• Find event: Search title/description
• Conflicts: Check overlapping times

Syncing

Run sync when data is stale or after any write operation:

~/.kiro/skills/google-calendar/scripts/sync.sh

---

Creating Events

Quick Add (natural language)

gcalcli quick "Lunch with Alex tomorrow at noon"

Detailed Add

gcalcli add \
  --title "Project Review" \
  --when "Feb 15 3:00 PM" \
  --duration 60 \
  --where "Conference Room A" \
  --description "Q1 review with the team" \
  --who "colleague@example.com" \
  --reminder "30m popup" \
  --noprompt

Add All-Day Event

gcalcli add \
  --title "Company Holiday" \
  --when "Mar 1" \
  --allday \
  --noprompt

Add to Specific Calendar

gcalcli add \
  --calendar "Work" \
  --title "Sprint Planning" \
  --when "Feb 17 10:00 AM" \
  --duration 90 \
  --noprompt

After creating: always run sync to update the local JSON file.

---

Editing Events

gcalcli edit --title "Event Title"

This opens an interactive editor. For non-interactive use, prefer deleting and re-creating the event.

---

Deleting Events

gcalcli delete --title "Event Title"

Use --noprompt to skip confirmation (use carefully).

After deleting: always run sync to update the local JSON file.

---

Searching Events

gcalcli search "keyword" "start date" "end date"

Example:

gcalcli search "standup" "Feb 1" "Feb 28"

---

Viewing Calendar

Agenda (list view)

gcalcli agenda "today" "7 days"

Week view

gcalcli calw 2

(Shows next 2 weeks)

Month view

gcalcli calm

---

Checking Conflicts

gcalcli conflicts "today" "7 days"

---

Listing Calendars

gcalcli list

---

Importing Events

gcalcli import -v event.ics

---

Important Notes

• Always use --noprompt when adding or deleting events to avoid

interactive prompts that block execution.

• Always run sync after any write operation (add/edit/delete) to

keep the local JSON file up to date.

• Timezone: User's timezone is Asia/Taipei. Always interpret and

display times in this timezone unless specified otherwise.

• Event colors: Available colors for --color: lavender, sage,

grape, flamingo, banana, tangerine, peacock, graphite, blueberry, basil, tomato.

• Reminders: Format is "TIME METHOD" — e.g., "30m popup", "1h email",

"1d popup". TIME units: w(weeks), d(days), h(hours), m(minutes).

Edge Cases

• No calendar file found: Run sync first via scripts/sync.sh
• Empty events: User has no upcoming events in the next 30 days
• OAuth expired: Run gcalcli init to re-authenticate
• Multiple calendars: Events from all calendars are included;

use --calendar flag to target a specific one

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ShaunTsai
• Source: ShaunTsai/skill-google-calendar
• License: MIT

Install and usage instructions live in the source repository linked above.