Agent skill

google-calendar

View and manage Google Calendar events. Check today's schedule, upcoming meetings, and calendar availability.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/google-calendar-tbroadley-dotfiles

SKILL.md

Google Calendar Integration

This skill provides access to Google Calendar via the Google Calendar API.

Setup Required

Uses OAuth with persistent refresh token (same setup for Calendar, Gmail, Drive).

One-time setup:

bash
google-oauth-setup <path-to-client-secret.json>

See claude/skills/SETUP.md for detailed OAuth setup instructions.

Get Access Token (auto-refreshes):

bash
ACCESS_TOKEN=$(google-oauth-token)

Required header for all requests:

bash
-H "x-goog-user-project: ${GOOGLE_QUOTA_PROJECT}"

When to Use

Use this skill when the user:

  • Asks about their calendar or schedule
  • Wants to see today's or upcoming meetings
  • Asks "what's on my calendar?"
  • Needs to check availability
  • Mentions meetings or events

API Endpoints

Base URL: https://www.googleapis.com/calendar/v3

List Calendars

bash
curl -s "https://www.googleapis.com/calendar/v3/users/me/calendarList" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, id}'

Get Events

Today's Events:

bash
TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -v+1d -u +"%Y-%m-%dT00:00:00Z")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${TODAY}" \
  --data-urlencode "timeMax=${TOMORROW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Next 7 Days:

bash
NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
WEEK=$(date -v+7d -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "timeMax=${WEEK}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=20" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Specific Date Range:

bash
curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=2024-01-15T00:00:00Z" \
  --data-urlencode "timeMax=2024-01-22T00:00:00Z" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Search Events

bash
curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "q=standup" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Get Single Event

bash
curl -s "https://www.googleapis.com/calendar/v3/calendars/primary/events/{EVENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Free/Busy Query

bash
curl -s -X POST "https://www.googleapis.com/calendar/v3/freeBusy" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "2024-01-15T00:00:00Z",
    "timeMax": "2024-01-16T00:00:00Z",
    "items": [{"id": "primary"}]
  }'

Common Workflows

What's on my calendar today?

bash
ACCESS_TOKEN=$(google-oauth-token)

TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
TOMORROW=$(date -v+1d -u +"%Y-%m-%dT00:00:00Z")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${TODAY}" \
  --data-urlencode "timeMax=${TOMORROW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {
    summary,
    start: (.start.dateTime // .start.date),
    end: (.end.dateTime // .end.date),
    location
  }'

What meetings do I have this week?

bash
NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
WEEK=$(date -v+7d -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "timeMax=${WEEK}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {
    summary,
    start: (.start.dateTime // .start.date),
    attendees: [.attendees[]?.email] | join(", ")
  }'

When is my next meeting?

bash
NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "timeMin=${NOW}" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[0] | {summary, start: .start.dateTime}'

Find a specific meeting

bash
curl -s -G "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  --data-urlencode "q=1:1" \
  --data-urlencode "singleEvents=true" \
  --data-urlencode "orderBy=startTime" \
  --data-urlencode "maxResults=5" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.items[] | {summary, start: .start.dateTime}'

Event Properties

Key fields in event responses:

  • summary: Event title
  • start.dateTime / start.date: Start time (dateTime for timed events, date for all-day)
  • end.dateTime / end.date: End time
  • location: Meeting location or video link
  • description: Event description
  • attendees: Array of attendee objects with email, responseStatus
  • hangoutLink: Google Meet link if present
  • htmlLink: Link to view event in Google Calendar

Parameters

Parameter Description
timeMin Lower bound (exclusive) for event end time (RFC3339)
timeMax Upper bound (exclusive) for event start time (RFC3339)
singleEvents Expand recurring events into instances (set to true)
orderBy startTime (requires singleEvents=true) or updated
maxResults Max events to return (default 250)
q Free text search terms

Notes

  • Times must be in RFC3339 format (e.g., 2024-01-15T09:00:00Z or with timezone offset)
  • Use singleEvents=true to expand recurring events
  • primary refers to the user's primary calendar; use calendar ID for others
  • Access tokens expire after 1 hour; refresh as needed
  • All-day events use start.date instead of start.dateTime

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results