---
slug: "skill-google-calendar"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/ShaunTsai/skill-google-calendar@main/SKILL.md"
repo: "https://github.com/ShaunTsai/skill-google-calendar"
source_file: "SKILL.md"
branch: "main"
---
---
name: google-calendar
description: >
  Full Google Calendar integration via gcalcli. Read, create, edit, delete,
  and search calendar events. Use when the user asks about their schedule,
  upcoming events, availability, meetings, or wants to manage their calendar.
  Triggers on keywords like calendar, schedule, meeting, event, free time,
  availability, agenda, add event, delete event, reschedule.
compatibility: Requires gcalcli, jq, and python3. Requires Google Calendar OAuth configured.
metadata:
  author: shaun-tsai
  version: "2.0"
allowed-tools: Bash(gcalcli:*) Bash(jq:*) Read
---

# 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 (< 1 hour): Use data directly
- Stale (1-6 hours): Use data but mention it may be slightly outdated
- Very stale (> 6 hours): Run sync first

### Step 2: Read Calendar Data

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

```json
{
  "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:

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

---

## Creating Events

### Quick Add (natural language)

```bash
gcalcli quick "Lunch with Alex tomorrow at noon"
```

### Detailed Add

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

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

### Add to Specific Calendar

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

```bash
gcalcli edit --title "Event Title"
```

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

---

## Deleting Events

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

```bash
gcalcli search "keyword" "start date" "end date"
```

Example:
```bash
gcalcli search "standup" "Feb 1" "Feb 28"
```

---

## Viewing Calendar

### Agenda (list view)

```bash
gcalcli agenda "today" "7 days"
```

### Week view

```bash
gcalcli calw 2
```
(Shows next 2 weeks)

### Month view

```bash
gcalcli calm
```

---

## Checking Conflicts

```bash
gcalcli conflicts "today" "7 days"
```

---

## Listing Calendars

```bash
gcalcli list
```

---

## Importing Events

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