gog-calendar

name	gog-calendar
description	Review calendar agenda, find available meeting slots, and schedule events. Displays today's or week's schedule, suggests meeting times based on availability, creates calendar events with explicit user confirmation. Use when user mentions calendar, schedule, meetings, or availability. Never creates or modifies events without confirmation.
compatibility	Requires gog CLI tool with calendar access
metadata	{"author":"gog-skills","version":"1.0"}
allowed-tools	Bash(gog:*) Read

Calendar & Scheduling Assistant

Review your schedule, find meeting slots, and create events with smart suggestions.

When to Use

Use this skill when:

• User asks "what's on my calendar" or "what meetings do I have today"
• User wants to "schedule a meeting" or "find time to meet"
• User mentions "check my availability"
• User says "when am I free this week"
• User wants to create a calendar event

Important: This skill NEVER creates or modifies events without explicit user confirmation.

Dynamic Context

The following live data is available:

Today's agenda:

!`gog calendar events --today --json 2>/dev/null || echo "GOG_NOT_CONFIGURED"`

Workflow

Reviewing Calendar

Today's Agenda

When user says "what's on my calendar today" or "show today's schedule":

1. Fetch today's events:

   gog calendar events --today --json
   

2. Present formatted agenda:

   # Today's Agenda — [Day], [Date]
   
   ## Morning
   
   **9:00 AM - 9:30 AM** | Team Standup
   - Location: Zoom (https://zoom.us/j/123...)
   - Attendees: Alice, Bob, Carol (3 people)
   - Status: Confirmed
   
   **10:00 AM - 11:00 AM** | 1:1 with Manager
   - Location: Conference Room A
   - Status: Confirmed
   
   ## Afternoon
   
   **2:00 PM - 3:30 PM** | Client Demo
   - Location: Zoom
   - Attendees: Client team (5 people)
   - Status: Confirmed
   - 📎 Has description/notes
   
   **4:00 PM - 5:00 PM** | Project Planning
   - Location: Virtual
   - Status: Tentative ⚠️
   
   ---
   
   **Summary**:
   - Total meetings: 4
   - Total time: 3.5 hours
   - Free blocks: 11:00 AM - 2:00 PM (3 hours)
   - Day ends at: 5:00 PM
   
   **Preparation needed**:
   - Review client demo slides (before 2pm)
   - Prepare 1:1 talking points (before 10am)
   

Week's Agenda

When user says "what's my week look like" or "show this week":

1. Fetch week's events:

   # Calculate date range for this week
   FROM_DATE=$(date +%Y-%m-%d)
   TO_DATE=$(date -v+7d +%Y-%m-%d)  # macOS
   
   # Fetch events in range
   gog calendar events --from "$FROM_DATE" --to "$TO_DATE" --json
   

2. Present grouped by day:

   # Week Agenda — Week of [Date]
   
   ## Monday, [Date]
   - 9:00 AM - 9:30 AM | Team Standup
   - 2:00 PM - 3:00 PM | Design Review
   [Total: 1.5 hours]
   
   ## Tuesday, [Date]
   - 9:00 AM - 9:30 AM | Team Standup
   - 10:00 AM - 12:00 PM | Workshop
   - 3:00 PM - 4:00 PM | Quarterly Review
   [Total: 3.5 hours]
   
   ## Wednesday, [Date]
   - 9:00 AM - 9:30 AM | Team Standup
   [Total: 0.5 hours] — Light day! 💚
   
   [...]
   
   ---
   
   **Week Summary**:
   - Total meetings: 15
   - Busiest day: Tuesday (3.5 hours)
   - Lightest day: Wednesday (0.5 hours)
   - Free afternoons: Wednesday, Friday
   

Finding Meeting Slots

When user says "find time for a meeting" or "when am I free":

1. Gather requirements:

   Let me find available meeting times. A few questions:
   
   1. **Duration**: How long should the meeting be? (30 min, 1 hour, etc.)
   2. **Date range**: When are you looking? (This week, next week, specific dates)
   3. **Time preferences**: Any time constraints? (Mornings only, after 2pm, etc.)
   4. **Attendees**: Anyone else's calendar to check? (If you have access)
   

2. Search for slots using freebusy:

   # Get busy periods
   gog calendar freebusy primary \
     --from "2026-01-29T00:00:00Z" \
     --to "2026-01-31T23:59:59Z" \
     --json
   

   Note: GOG CLI v0.9.0 doesn't have find-slots. Instead, use freebusy to get busy periods, then calculate free gaps between them. For example:

   • If busy: 9-10am, 2-3pm
   • Then free: 8-9am, 10am-2pm, 3-5pm

   Parse the busy periods and suggest slots in the free time.

3. Present options:

   # Available Meeting Slots
   
   ## Top 5 Options (60 minutes)
   
   1. **Wednesday, Jan 29 at 2:00 PM - 3:00 PM**
      - Ideal time: After lunch, before end of day
      - No conflicts
   
   2. **Thursday, Jan 30 at 10:00 AM - 11:00 AM**
      - Morning slot, good energy
      - No conflicts
   
   3. **Thursday, Jan 30 at 3:00 PM - 4:00 PM**
      - Afternoon slot
      - No conflicts
   
   4. **Friday, Jan 31 at 9:00 AM - 10:00 AM**
      - Early morning
      - No conflicts
   
    
    Post-lunch
    No conflicts
   
   ---
   
   : Option 1 (Wed at 2pm) — Best mid-week timing
   
   Which slot works best? Or need more options?
   

Creating Events

When user says "schedule a meeting" or "create a calendar event":

1. Gather event details:

   Let me create that calendar event. I need:
   
   1. **Title**: What's the meeting about?
   2. **Date & Time**: When? (e.g., "Tomorrow at 2pm", "Jan 30 at 10am")
   3. **Duration**: How long? (30 min, 1 hour, 90 min, etc.)
   4. **Attendees**: Who should attend? (email addresses, comma-separated)
   5. **Location**: Where? (Zoom, physical location, or I can generate a meeting link)
   6. **Description**: Any agenda or notes?
   

2. Parse date/time:

   • Support natural language: "tomorrow at 2pm", "next Tuesday at 10am"
   • Convert to ISO8601: "2026-01-29T14:00:00Z"
   • Confirm timezone assumptions

3. Present proposed event:

   ## Proposed Event
   
   **Title**: Q2 Planning Meeting
   **Date**: Wednesday, January 29, 2026
   **Time**: 2:00 PM - 3:00 PM (1 hour)
   **Attendees**:
   - [e-mail]
   - [e-mail]
   - [e-mail]
   **Location**: Zoom (meeting link will be generated)
   **Description**: Discuss Q2 goals, budget allocation, and team priorities.
   
   **Conflicts check**: ✅ No conflicts found for you
   
   ⚠️  **Note**: Cannot check attendees' availability without access to their calendars.
   
   Does this look correct? Any changes needed?
   

4. Request confirmation:

   Ready to create this event? It will:
   - Add to your calendar
   - Send invitations to all attendees
   - Generate meeting link (if applicable)
   
   Reply "yes, create" to confirm.
   

5. Only create with explicit confirmation: "yes, create" or "create it"

Modifying Events

Not implemented in MVP - User should use calendar client directly for modifications. If user requests, suggest:

To modify this event, please use your calendar app directly:
- Google Calendar: calendar.google.com
- Outlook: outlook.office.com

Or tell me what you'd like to change and I can help you communicate it to attendees via email.

Output Format (Strict)

Agenda View (Daily)

# Today's Agenda — [Day], [Date]

## Morning
[Time range] | [Title]
- Location: [location]
- Attendees: [count or names]
- Status: [Confirmed/Tentative]

## Afternoon
[Same format]

---

**Summary**:
- Total meetings: [N]
- Total time: [X hours]
- Free blocks: [time ranges]

**Preparation needed**:
- [Action items before meetings]

Meeting Slot Options

# Available Meeting Slots

## Top [N] Options ([duration])

1. **[Day, Date] at [Time] - [Time]**
   - [Context/rationale]
   - [Conflict status]

[...]

---

**Recommendation**: [Which slot and why]

Event Creation Confirmation

## Proposed Event

[All event details clearly listed]

**Conflicts check**: [Status]

Does this look correct?

---

Ready to create? Reply "yes, create" to confirm.

Event Created Success

✅ **Event Created**

Event ID: [id]
Title: [title]
When: [readable date/time]
Invitations sent to: [N attendees]

**Next steps**: [Suggested follow-up actions]

Examples

Example 1: Today's Agenda

User: "What's on my calendar today?"

Assistant:

[Fetches today's agenda...]

# Today's Agenda — Tuesday, January 28

## Morning

**9:00 AM - 9:30 AM** | Team Standup
- Location: Zoom (https://zoom.us/j/123456789)
- Attendees: Engineering team (8 people)
- Status: Confirmed

**11:00 AM - 12:00 PM** | Product Review
- Location: Conference Room B
- Attendees: Product, Design, Eng leads
- Status: Confirmed

## Afternoon

**2:00 PM - 3:30 PM** | Client Demo — Acme Corp
- Location: Zoom
- Attendees: 5 external guests
- Status: Confirmed
- 📎 Agenda: Demo new features, Q&A, pricing discussion

**4:00 PM - 4:30 PM** | 1:1 with Sarah
- Location: Her office
- Status: Confirmed

---

**Summary**:
- Total meetings: 4
- Total time: 3.5 hours
- Free blocks: 9:30 AM - 11:00 AM (1.5 hrs), 12:00 PM - 2:00 PM (2 hrs)
- Day ends at: 4:30 PM

**Preparation needed**:
- Finish demo slides (before 2pm)
- Review Acme account history (before 2pm)
- Prepare 1:1 talking points for Sarah (before 4pm)

Your afternoon is packed. Want me to help prep for the client demo?

Example 2: Schedule a Meeting

User: "Schedule a meeting with [e-mail] and [e-mail] for tomorrow at 2pm, 1 hour, to discuss Q2 budget"

Assistant:

## Proposed Event

**Title**: Q2 Budget Discussion
**Date**: Wednesday, January 29, 2026
**Time**: 2:00 PM - 3:00 PM (1 hour)
**Attendees**:
- [e-mail]
- [e-mail]
**Location**: Virtual meeting (Zoom link will be generated)
**Description**: Discuss Q2 budget allocation and priorities.

**Conflicts check**: ✅ No conflicts found on your calendar

⚠️  **Note**: Cannot check Alice and Bob's availability without calendar access. The invitation will ask them to accept/decline.

Does this look correct? Any changes needed?

User: "Looks good, create it"

Assistant:

Ready to create this event? It will:
- Add to your calendar
- Send invitations to Alice and Bob
- Generate a Zoom meeting link

Reply "yes, create" to confirm.

User: "yes, create"

Assistant:

[Creates event...]

✅ **Event Created**

Event ID: event_xyz789
Title: Q2 Budget Discussion
When: Wednesday, Jan 29 at 2:00 PM (1 hour)
Location: Zoom — https://zoom.us/j/987654321
Invitations sent to: 2 attendees ([e-mail], [e-mail])

**Next steps**:
- Prepare budget spreadsheet?
- Draft agenda email to attendees?
- Create task for pre-meeting prep?

Want me to draft an agenda email to Alice and Bob?

Example 3: Find Meeting Slots

User: "When am I free for a 30-minute meeting this week?"

Assistant:

Let me check your availability.

[Searches calendar...]

# Available Meeting Slots

## Top 5 Options (30 minutes)

1. **Wednesday, Jan 29 at 10:00 AM - 10:30 AM**
   - Morning slot, good focus time
   - No conflicts before or after

2. **Wednesday, Jan 29 at 3:00 PM - 3:30 PM**
   - Afternoon slot
   - 1 hour buffer before next meeting

3. **Thursday, Jan 30 at 9:00 AM - 9:30 AM**
   - Early morning, fresh start
   - No conflicts

4. **Thursday, Jan 30 at 2:00 PM - 2:30 PM**
   - Post-lunch
   - No conflicts

5. **Friday, Jan 31 at 11:00 AM - 11:30 AM**
   - Late morning
   - Last slot before lunch

---

**Recommendation**: Option 1 (Wed at 10am) — Quietest day, good timing

Which slot works for you? Or need to check other times?

Failure Modes / Troubleshooting

GOG Not Configured

Symptom: Dynamic context shows GOG_NOT_CONFIGURED

Resolution:

1. Inform: "GOG CLI is not configured. See: skills/gog/_shared/references/gog-interface.md"
2. Suggest: "Run gog auth login to authenticate with calendar access"
3. Offer: "I can still help you plan scheduling manually"

Ambiguous Date/Time

Symptom: User says "schedule meeting tomorrow" without specifying time

Resolution:

1. Ask: "What time tomorrow? (e.g., 2pm, morning, afternoon)"
2. If still vague, suggest: "Would 2:00 PM work? (mid-afternoon, typical meeting time)"
3. Always confirm parsed date/time before creating

Timezone Confusion

Symptom: User is in different timezone than system

Resolution:

1. Check system timezone: date +%Z
2. Ask user: "I'm showing times in [TZ]. Is that correct for you?"
3. If mismatch, clarify: "So 2pm your time is [X]pm [TZ], correct?"
4. Always display timezone in event confirmations

No Available Slots

Symptom: Calendar is fully booked, no free slots found

Resolution:

1. Inform: "Your calendar is packed for [date range]. No [duration] slots available."
2. Suggest alternatives:
   • "Extend to next week?"
   • "Shorten meeting to [shorter duration]?"
   • "Consider before 9am or after 5pm?"
3. Show least-conflict options: "These times have only 1 conflict..."

Attendee Email Typo

Symptom: User provides malformed email address

Resolution:

1. Detect invalid format (no @, invalid domain)
2. Warn: "The email '[address]' doesn't look valid. Please double-check."
3. Ask: "Did you mean [suggested correction]?"
4. Don't create event with invalid emails

Conflict with Existing Event

Symptom: Proposed time overlaps with existing event

Resolution:

1. Warn: "⚠️ Conflict detected: You have '[Event Title]' at that time."
2. Ask: "Should I:
   • Find a different time?
   • Create anyway (double-booked)?
   • Reschedule the conflicting event?"
3. Require explicit confirmation for double-booking

Safety Rules

1. Never create events without confirmation - Always show proposal and request "yes, create"
2. No modifications without confirmation - Editing events requires explicit approval
3. Timezone awareness - Always clarify and confirm timezone in summaries
4. Privacy in invites - Don't include sensitive info in event titles/descriptions
5. Invitation transparency - Tell user who will receive invitations before creating

Safe Test

To safely test this skill using only [e-mail]:

Test 1: View Agenda (Read-Only, Always Safe)

In Claude Code:

1. Load gog-calendar skill
2. Say: "Show today's agenda"
3. Verify output includes:
   • Events for today (or "No events" if empty)
   • Time, title, location, attendees
   • Summary with meeting count and free blocks

Test 2: Find Slots (Read-Only, Always Safe)

1. Say: "When am I free for a 30-minute meeting tomorrow?"
2. Verify output includes:
   • List of available time slots
   • Duration specified
   • Recommendation
3. Confirm no events are created

Test 3: Create Event (Draft-to-Self Only, Safe)

1. Say: "Schedule a test meeting with [e-mail] tomorrow at 3pm, 30 minutes, test meeting"
2. Review proposed event
3. Say: "yes, create"
4. Verify event is created
5. Check your calendar to confirm event appears
6. Delete the test event afterward

See skills/gog/_shared/references/testing.md for complete test plan.

Notes

• This skill integrates with:

  • gog-email-triage: Calendar conflicts inform email prioritization
  • gog-email-draft: Can draft meeting invitations or agenda emails
  • gog-tasks: Meeting prep can become tasks
  • gog-followups: Track meeting follow-ups

• Consider creating event templates for recurring meetings (1:1s, standups)

• For recurring events, user should use calendar client directly (more complex to create via CLI)

• Smart scheduling tips:

  • Batch meetings on certain days, leave other days meeting-free
  • Suggest "No Meeting Fridays" if calendar is too full
  • Recommend buffer time between back-to-back meetings

• If GOG supports it, integrate with video conferencing (auto-generate Zoom links, etc.)

• Future enhancement: Analyze meeting patterns and suggest optimization