ankitjh4/skill-builder/google-calendar

Google Calendar Skill

Query your calendar and find free time using your direct Google OAuth connection.

Prerequisites

Set up the google-direct-oauth skill first. You should have valid tokens at /home/.z/google-oauth/token.json. These credentials can also be reused by gog if you install that external skill.

Usage

The main script is scripts/gcal.py. Run with --help for all options:

python Skills/google-calendar/scripts/gcal.py --help

List Events

# Today's events
python scripts/gcal.py events
 
# Specific date
python scripts/gcal.py events 2026-01-25
python scripts/gcal.py events tomorrow
python scripts/gcal.py events "next monday"

Find Free Time

# Free blocks today (9am-6pm, min 15 min)
python scripts/gcal.py free
 
# Custom hours
python scripts/gcal.py free tomorrow --start 10 --end 16
 
# Longer blocks only
python scripts/gcal.py free friday --min-duration 60

Week Overview

python scripts/gcal.py week

JSON Output (for programmatic use)

python scripts/gcal.py json today

For Zo

When the user asks about their calendar:

1. "What's on my calendar [date]?" → Run events command
2. "When am I free [date]?" → Run free command
3. "Show my week" → Run week command
4. "Find me a 1-hour slot tomorrow afternoon" → Run free tomorrow --start 12 --end 18 --min-duration 60

Parse natural language dates:

• "today", "tomorrow", "yesterday"
• "next monday", "next friday"
• "January 25" → "01-25"
• "2026-01-25"