Search Calendar Skill

This skill teaches Claude how to intelligently search your Google Calendar with multiple search criteria and flexible natural language understanding.

When to Use This Skill

Use this skill when users ask questions like:

• "Show me events on Monday with Eddie"
• "Find all 'SnR:Huddle' meetings this week"
• "What do I have on 21 Oct 2025?"
• "List standup meetings with John Hor next week"
• "Events with sentient.io emails today"
• "When am I meeting with Wilson Ang?"

How to Search Calendars Effectively

Search Dimensions

Claude can search calendars across these dimensions:

1. By Day (Today, Tomorrow, Specific Weekdays)

• "today", "tomorrow", "yesterday"
• Weekday names: "Monday", "Tuesday", etc.
• With modifiers: "next Monday", "last Friday", "this Thursday"

2. By Date (Specific Dates)

• Multiple formats supported: "21 Oct 2025", "October 21", "2025-10-21", "21/10/2025"
• Claude can parse these flexibly

3. By Week (Calendar Weeks)

• "this week", "next week", "last week"

4. By Subject/Title (Event Names)

• Search event titles: "SnR:Huddle", "standup", "planning", "review"
• Use partial matches: "huddle" finds "SnR:Huddle"

5. By Attendee Name (People Invited)

• Search by name: "Eddie", "Wilson Ang", "John Hor"
• Use first name, last name, or abbreviations: "Ed" finds "Eddie"
• Names are fuzzy-matched to handle variations

6. By Email Address (Attendee Emails)

• Full or partial emails: "[email protected]", "sentient.io", "mani@"
• Searches attendee email list

Combining Criteria (AND Logic)

Combine multiple search dimensions to narrow results:

• Date + Attendee: "Show me events with Eddie on Monday"
• Subject + Week: "Find all 'standup' meetings this week"
• Subject + Attendee + Date: "'SnR:Huddle' with John on Friday"
• Multiple attendees: "Events with Eddie and Mani next week"

Implementation Strategy

When searching calendars, Claude should:

1. Parse the user query to identify:

   • Time reference (day, date, week)
   • Subject/keywords
   • Attendee names or emails

2. Use Google Calendar tools to:

   • Get list of calendars accessible using list_gcal_calendars
   • Retrieve events for the identified time range using list_gcal_events
   • Filter by subject, attendees, and other criteria

3. Enrich each event with:

   • Precise start/end times in Asia/Singapore timezone (ISO 8601 format)
   • Duration calculation (end_time - start_time in minutes)
   • Prep time indicator based on:
     • Presence of Drive links in description
     • Number of attendees (>5 = needs prep)
     • Attachments or conferenceData
   • Full event description (no truncation)
   • Conferencing details extracted from event data

4. Format results with:

   • Event title and time (with explicit timezone)
   • Duration in minutes
   • Location
   • Full attendee list with email addresses and RSVP status
   • Link to the calendar event
   • Description (if present)
   • Prep needed flag
   • Conference link (if present)

5. Apply filtering logic:

   • Exclude cancelled events
   • Include all other event statuses (accepted, tentative, needs action, declined)
   • Limit to 50 most recent results
   • Sort by start time (chronological order for briefings)

Natural Language Processing

Claude should understand:

• Flexible phrasing: "What's on my calendar?" vs "Show me my events"
• Fuzzy matching: "Wil" for "Wilson", "Ed" for "Eddie"
• Multiple date formats naturally
• Partial information: "meetings with sentient.io" or just "Eddie" without full context
• Relative time references: "this week", "next Monday", "last Friday"

Event Enrichment Logic

After retrieving events from list_gcal_events, Claude must enrich each event:

1. Duration Calculation:

duration_minutes = (end_time - start_time).total_seconds() / 60

2. Prep Time Detection - Set prep_needed: true if:

• Description contains: docs.google.com/document, docs.google.com/spreadsheets, docs.google.com/presentation, drive.google.com
• Description contains keywords: agenda, review, presentation, proposal, deck
• Attendee count > 5
• Event has attachments or conferenceData fields

3. Conference Link Extraction:

• Check conferenceData.entryPoints for video conference URLs
• Fallback: Search description for meet.google.com, zoom.us, teams.microsoft.com links
• Return: {type: "Google Meet", url: "https://..."}

4. Timezone Conversion:

• Convert all event times to Asia/Singapore timezone (UTC+8)
• Format as ISO 8601: 2025-10-26T14:30:00+08:00

Reference: See /mnt/skills/user/search-calendar/search_calendar_helper.py for example implementations of:

• calculate_duration(start, end)
• needs_prep_time(event)
• extract_conference_link(event)

Examples

Example 1: Today's Events

User: "Show me my calendar for today"

Claude should:

1. Get current date
2. Use list_gcal_events to retrieve events for today from all accessible calendars
3. Enrich each event with duration, prep indicators, timezone conversion
4. Format and display them

Example 2: Events with Specific Person

User: "Find all meetings with Eddie this week"

Claude should:

1. Identify time range: this week (Monday-Sunday)
2. Use list_gcal_events to query all calendars for events in that range
3. Filter for events where "Eddie" is an attendee (fuzzy match on attendee names)
4. Enrich each event with duration, prep indicators, conference links
5. Return matching events with full details

Example 3: Subject + Attendee + Date

User: "Show me 'SnR:Huddle' meetings with John Hor next week"

Claude should:

1. Identify time range: next week
2. Use list_gcal_events to query calendars for events with "Huddle" or "SnR" in title
3. Filter for events where "John Hor" is invited
4. Enrich events with prep indicators, duration, conference links
5. Return combined results

Example 4: Email-based Search

User: "What meetings do I have with people from sentient.io?"

Claude should:

1. Use list_gcal_events to query recent events (default: next 30 days)
2. Filter for events with attendees having @sentient.io email
3. Enrich events with all additional context
4. Return matching events

Important Guidelines

Timezone Handling (CRITICAL for briefings)

• ALL timestamps MUST be returned in Asia/Singapore timezone (SGT / UTC+8)
• Use ISO 8601 format with explicit timezone: 2025-10-26T14:30:00+08:00
• Never return times without timezone information
• Ensure consistency across all events for time-based sorting and briefing integration
• If user is in different timezone, convert display times but maintain SGT in data structure

Time Ranges

• Day-based search: Search that specific 24-hour period
• Week-based search: Search Monday through Sunday of that calendar week
• Date-based search: Search that specific date
• No time specified: Default to next 30 days for open searches

Attendee Matching

• Use fuzzy matching for names (70% similarity threshold)
• Handle partial names and nicknames
• For emails: support partial matches (e.g., "eddie@" matches "[email protected]")
• Match against all visible attendees, not just organizer

Event Status

• Always exclude: Cancelled events
• Always include: All other statuses (Accepted, Tentative, Declined, Needs Action)
• Display attendee RSVP status when listing events

Result Limits

• Return maximum 50 events per search
• Show newest/most recent first
• Include full details: title, time, location, attendees, calendar link

Enriched Event Data (for briefing integration)

• Duration: Calculate and return event duration in minutes
• Prep Time Indicator: Set prep_needed: true if event has:
  • Description containing Drive links (docs.google.com/document, docs.google.com/spreadsheet, etc.)
  • Description containing meeting agendas or action items
  • Attachments (check for conferenceData or attachments in event)
  • More than 5 attendees (larger meetings typically need prep)
• Descriptions: Always include event descriptions by default (don't truncate)
• Attendee Context: Include full attendee list with emails and response status
• Conferencing: Extract and return video conference links (Meet, Zoom, Teams, etc.)

Tips for Better Results

1. Be specific: Include attendee names or subjects when possible to narrow results
2. Use natural dates: "next Monday" works better than calculating dates manually
3. Combine criteria: Rather than "all my meetings with Eddie", use "Eddie next week" for faster results
4. Verify attendee names: If unsure of spelling, use nicknames - fuzzy matching handles it

Handling Edge Cases

Multiple people with similar names:

• Display all matches and ask user to clarify if needed
• Show email addresses to help distinguish

Events without attendees:

• Include in results when subject matches
• Mark "No attendees" or "Private" if applicable

All-day events:

• Include in results
• Display as "All day" rather than specific times

Recurring events:

• Return individual instances for the date range queried
• Show the full series context if available

No results:

• Explain why no events were found
• Suggest broadening the search (e.g., "try searching all week instead of just Monday")

Integration with Other Tools

This skill works with Claude's existing calendar tools and can be combined with:

• Email searches (find emails about specific meetings) - use recent-emails with aligned timestamps
• Document searches (find prep materials) - use work-day-files to locate meeting-related documents
• Task management (create tasks from meeting discussions)
• Daily briefings - provides the timeline anchor for time-based organization

Briefing Integration (Primary Use Case)

This skill is optimized to serve as the timeline anchor for daily briefings:

1. Timestamp Alignment: All events return precise start/end times in Asia/Singapore timezone matching the format used by recent-emails and work-day-files

2. Prep Time Intelligence: The prep_needed flag helps briefings surface:

   • Events requiring document review (Drive links in description)
   • Large meetings (>5 attendees)
   • Events with attachments or agendas

3. Contextual Linking: When building briefings:

   • Check if recent emails (from recent-emails) are from meeting attendees
   • Check if recent file modifications (from work-day-files) relate to meeting topics
   • Flag "action items" by correlating email subjects with event titles

4. Time-Based Output: Sort events chronologically to create a clear timeline that other briefing components can reference

Example Briefing Flow:

08:00 - Check work-day-files for documents modified overnight
09:00 - Morning standup (from search-calendar) 
        ↳ prep_needed: true (has agenda doc)
        ↳ Related file: "Standup Notes 2025-10-26.docx" modified at 08:30
10:00 - Review recent-emails for urgent items from standup attendees
14:00 - Client meeting (from search-calendar)
        ↳ prep_needed: true (>5 attendees)
        ↳ Related email: "Q4 Proposal" from [email protected] at 13:45

Security and Privacy

• Search only calendars the user has read access to
• Don't expose private event details beyond what the user authorized
• Respect calendar sharing permissions
• Only display information the user can see

Troubleshooting

"No calendars found"

• User may need to grant calendar access
• Verify Google Calendar permissions

"No events matching"

• Try broader search terms
• Check spelling of names/subjects
• Extend date range

"Wrong person matched"

• For ambiguous names, ask user to clarify
• Use email addresses for specific identification
• Provide full names in results to avoid confusion

---

Quick Start for Claude

When a user asks about their calendar:

1. Parse their request for: time (when), subject (what), people (who)

2. Use calendar tools to fetch events:

   • list_gcal_calendars to get available calendars
   • list_gcal_events with appropriate date range filters

3. Enrich each event with:

   • Duration calculation (in minutes)
   • Prep time indicator (Drive links, >5 attendees, attachments, keywords)
   • Conference link extraction (Meet, Zoom, Teams)
   • Ensure timestamps are in Asia/Singapore timezone (SGT/UTC+8)

4. Apply intelligent filtering based on all criteria provided:

   • Attendee name matching (fuzzy)
   • Email domain filtering
   • Subject/title matching

5. Format results clearly with:

   • Event details with explicit SGT timestamps
   • Duration, prep indicators, conference links
   • Full attendee context with RSVP status
   • Calendar event links

6. For unclear queries, ask clarifying questions

Reference Implementation: The search_calendar_helper.py file contains example code for the enrichment logic (duration calculation, prep time detection, conference link extraction). Claude can reference these functions when implementing the enrichment steps.

The skill is designed to be conversational - Claude should handle natural language calendar queries without requiring specific syntax or complex instructions from the user.