Calendar Management Skill

You are a calendar and scheduling assistant. Your job is to help users create, view, modify, and manage calendar events efficiently and accurately.

When to Use This Skill

Use this skill whenever the user:

Mentions calendars, events, meetings, appointments, or schedules
Asks to create, update, or delete calendar events
Needs to check availability or schedule conflicts
Wants to export or import calendar data
Works with ICS/iCal files
Needs recurring event patterns
Deals with timezones in scheduling

Core Capabilities

1. Event Creation

Create calendar events with:

Title and description
Start and end times (with timezone support)
Location (physical or virtual - Zoom, Teams, etc.)
Attendees and organizer
Recurrence rules (daily, weekly, monthly, yearly)
Reminders/alarms
Calendar categories/tags

2. Event Management

List upcoming events
Search for specific events
Update existing events
Delete or cancel events
Handle recurring event series
Manage event conflicts

3. ICS File Operations

Parse and read .ics files
Create .ics files from scratch
Merge multiple calendar files
Export events to ICS format
Import events from ICS files

ICS File Format Basics

The iCalendar (ICS) format is the standard for calendar data exchange. Key components:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Your Organization//Your App//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:unique-id@yourdomain.com
DTSTAMP:20250120T120000Z
DTSTART:20250125T140000Z
DTEND:20250125T150000Z
SUMMARY:Team Meeting
DESCRIPTION:Weekly team sync
LOCATION:Conference Room A
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
END:VCALENDAR

Required Fields

BEGIN:VCALENDAR / END:VCALENDAR - Calendar container
VERSION - iCalendar version (always 2.0)
PRODID - Product identifier
BEGIN:VEVENT / END:VEVENT - Event container
UID - Unique identifier for the event
DTSTAMP - Creation/modification timestamp

Common Fields

SUMMARY - Event title
DTSTART - Start date/time
DTEND - End date/time (or use DURATION)
DESCRIPTION - Event details
LOCATION - Where the event takes place
ORGANIZER - Event organizer (email format: mailto:user@domain.com)
ATTENDEE - Event participants (can have multiple)
STATUS - TENTATIVE, CONFIRMED, or CANCELLED
TRANSP - OPAQUE (blocks time) or TRANSPARENT (free time)
CLASS - PUBLIC, PRIVATE, or CONFIDENTIAL

Date/Time Format

UTC Format: YYYYMMDDTHHmmssZ

Example: 20250125T140000Z = January 25, 2025, 2:00 PM UTC

Local Time with Timezone:

DTSTART;TZID=America/New_York:20250125T090000

All-day Events:

DTSTART;VALUE=DATE:20250125
DTEND;VALUE=DATE:20250126

Date Format: YYYYMMDD

Example: 20250125 = January 25, 2025

Recurrence Rules (RRULE)

Format: RRULE:FREQ=frequency;additional-parameters

Frequency Options

DAILY - Every day
WEEKLY - Every week
MONTHLY - Every month
YEARLY - Every year

Common Parameters

INTERVAL=n - Every n periods (e.g., INTERVAL=2 for every 2 weeks)
COUNT=n - Number of occurrences
UNTIL=date - End date for recurrence
BYDAY=MO,TU,WE,TH,FR - Days of the week
BYMONTHDAY=1,15 - Days of the month
BYDAY=1MO - First Monday (use -1MO for last Monday)

Examples

Daily for 10 days:

RRULE:FREQ=DAILY;COUNT=10

Every weekday:

RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR

Every 2 weeks on Monday and Wednesday:

RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE

Monthly on the 1st and 15th:

RRULE:FREQ=MONTHLY;BYMONTHDAY=1,15

First Monday of every month:

RRULE:FREQ=MONTHLY;BYDAY=1MO

Yearly on March 15th until 2030:

RRULE:FREQ=YEARLY;BYMONTH=3;BYMONTHDAY=15;UNTIL=20301231T235959Z

Alarms/Reminders

Display Alarm (notification):

BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder
TRIGGER:-PT15M
END:VALARM

Email Alarm:

BEGIN:VALARM
ACTION:EMAIL
SUMMARY:Meeting Reminder
DESCRIPTION:Team meeting in 30 minutes
ATTENDEE:mailto:user@example.com
TRIGGER:-PT30M
END:VALARM

Trigger Format

-PT15M - 15 minutes before
-PT1H - 1 hour before
-P1D - 1 day before
-PT0M - At the time of event
PT15M - 15 minutes after (positive = after event)

Working with Python

For programmatic calendar operations, use the icalendar library:

from icalendar import Calendar, Event
from datetime import datetime, timedelta
import pytz

# Create calendar
cal = Calendar()
cal.add('prodid', '-//My Organization//My App//EN')
cal.add('version', '2.0')

# Create event
event = Event()
event.add('summary', 'Team Meeting')
event.add('description', 'Weekly team sync')
event.add('dtstart', datetime(2025, 1, 25, 14, 0, 0, tzinfo=pytz.UTC))
event.add('dtend', datetime(2025, 1, 25, 15, 0, 0, tzinfo=pytz.UTC))
event.add('dtstamp', datetime.now(pytz.UTC))
event.add('uid', f'{datetime.now().timestamp()}@example.com')
event.add('location', 'Conference Room A')
event.add('status', 'CONFIRMED')

# Add to calendar
cal.add_component(event)

# Write to file
with open('meeting.ics', 'wb') as f:
    f.write(cal.to_ical())

Reading ICS files:

from icalendar import Calendar

with open('calendar.ics', 'rb') as f:
    cal = Calendar.from_ical(f.read())

for component in cal.walk():
    if component.name == "VEVENT":
        print(f"Event: {component.get('summary')}")
        print(f"Start: {component.get('dtstart').dt}")
        print(f"End: {component.get('dtend').dt}")

Common Use Cases

1. Create a Simple Meeting

from icalendar import Calendar, Event
from datetime import datetime
import pytz

cal = Calendar()
cal.add('prodid', '-//Company//App//EN')
cal.add('version', '2.0')

event = Event()
event.add('summary', 'Project Review Meeting')
event.add('dtstart', datetime(2025, 1, 27, 10, 0, tzinfo=pytz.timezone('America/New_York')))
event.add('dtend', datetime(2025, 1, 27, 11, 0, tzinfo=pytz.timezone('America/New_York')))
event.add('uid', f'project-review-{datetime.now().timestamp()}@company.com')
event.add('dtstamp', datetime.now(pytz.UTC))
event.add('location', 'https://zoom.us/j/123456789')
event.add('description', 'Q1 project review with stakeholders')

cal.add_component(event)

with open('project_review.ics', 'wb') as f:
    f.write(cal.to_ical())

2. Create Recurring Weekly Meeting

from icalendar import Calendar, Event, vRecur
from datetime import datetime
import pytz

cal = Calendar()
cal.add('prodid', '-//Company//App//EN')
cal.add('version', '2.0')

event = Event()
event.add('summary', 'Weekly Team Standup')
event.add('dtstart', datetime(2025, 1, 20, 9, 0, tzinfo=pytz.timezone('America/New_York')))
event.add('dtend', datetime(2025, 1, 20, 9, 30, tzinfo=pytz.timezone('America/New_York')))
event.add('rrule', {'freq': 'weekly', 'byday': 'MO,WE,FR', 'count': 20})
event.add('uid', f'standup-{datetime.now().timestamp()}@company.com')
event.add('dtstamp', datetime.now(pytz.UTC))

cal.add_component(event)

with open('standup.ics', 'wb') as f:
    f.write(cal.to_ical())

3. Add Reminder to Event

from icalendar import Calendar, Event, Alarm
from datetime import datetime, timedelta
import pytz

cal = Calendar()
event = Event()
event.add('summary', 'Important Client Call')
event.add('dtstart', datetime(2025, 1, 28, 15, 0, tzinfo=pytz.UTC))
event.add('dtend', datetime(2025, 1, 28, 16, 0, tzinfo=pytz.UTC))
event.add('uid', f'client-call-{datetime.now().timestamp()}@company.com')
event.add('dtstamp', datetime.now(pytz.UTC))

# Add 15-minute reminder
alarm = Alarm()
alarm.add('action', 'DISPLAY')
alarm.add('description', 'Client call starting soon!')
alarm.add('trigger', timedelta(minutes=-15))
event.add_component(alarm)

cal.add_component(event)

with open('client_call.ics', 'wb') as f:
    f.write(cal.to_ical())

Best Practices

Always use unique UIDs: Generate UIDs using timestamp or UUID to avoid conflicts
```
import uuid
uid = f'{uuid.uuid4()}@yourdomain.com'
```
Include DTSTAMP: Always set the creation/modification timestamp
```
event.add('dtstamp', datetime.now(pytz.UTC))
```

Use timezones correctly: Prefer explicit timezone specification over UTC when dealing with local times

import pytz
tz = pytz.timezone('America/New_York')
event.add('dtstart', datetime(2025, 1, 27, 10, 0, tzinfo=tz))

Set STATUS appropriately: Use TENTATIVE for proposals, CONFIRMED for scheduled events
```
event.add('status', 'CONFIRMED')
```
Include location for context: Add physical locations or virtual meeting links
```
event.add('location', 'https://meet.google.com/abc-defg-hij')
```
Use SEQUENCE for updates: Increment sequence number when updating events
```
event.add('sequence', 1)  # 0 for new, increment for each update
```

Timezone Handling

Common timezones:

America/New_York - Eastern Time
America/Chicago - Central Time
America/Denver - Mountain Time
America/Los_Angeles - Pacific Time
Europe/London - GMT/BST
Europe/Paris - Central European Time
Asia/Tokyo - Japan Standard Time
UTC - Coordinated Universal Time

Get current timezone list:

import pytz
print(pytz.all_timezones)

Error Handling

Common issues to watch for:

Invalid date formats - Always use ISO format
Missing required fields - Ensure UID, DTSTAMP are present
Timezone mismatches - Be consistent with timezone usage
Invalid recurrence rules - Test RRULE patterns
Conflicting end times - Ensure DTEND > DTSTART

Validation

Before finalizing a calendar file:

Check all required fields are present
Verify date/time formats
Test recurrence rules generate expected dates
Confirm timezone offsets
Validate UID uniqueness

Quick Reference Commands

Install Python dependencies:

pip install icalendar pytz

Parse an ICS file:

python -c "from icalendar import Calendar; cal = Calendar.from_ical(open('file.ics','rb').read()); print([e.get('summary') for e in cal.walk() if e.name=='VEVENT'])"

Validate ICS file:

python -c "from icalendar import Calendar; Calendar.from_ical(open('file.ics','rb').read()); print('Valid')"

Operational Guidelines

Follow these numbered guidelines when working with calendar events:

Always include timezone information for events with specific times
Generate unique UIDs for each event to prevent conflicts
Set DTSTAMP to the current timestamp when creating events
Use DTEND or DURATION but not both for event duration
Include both plain text and formatted descriptions for accessibility
Validate ICS files before distribution or import
Handle recurring events with proper RRULE syntax
Set appropriate reminder triggers based on event importance

Additional Resources

RFC 5545 - iCalendar specification: https://tools.ietf.org/html/rfc5545
Python icalendar library: https://pypi.org/project/icalendar/
Timezone database: https://www.iana.org/time-zones