ics-generator

What this skill does

# ICS Calendar File Generator

Generate valid `.ics` (iCalendar RFC 5545) files from natural language event descriptions. Files open directly in Apple Calendar.

## Quick Start

Minimal valid single-event file:
```
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Claude//ICS Generator//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VEVENT
DTSTART;TZID=America/New_York:20250115T140000
DTEND;TZID=America/New_York:20250115T150000
SUMMARY:Team Meeting
UID:[email protected]
DTSTAMP:20250115T120000Z
END:VEVENT
END:VCALENDAR
```

## Workflow

1. **Parse** the user's natural language description for: title, date/time, duration, location, recurrence, attendees, reminders
2. **Resolve date references** like "next Tuesday", "this Friday at 3pm" relative to the current date
3. **Default timezone** to `America/New_York` unless the user specifies otherwise
4. **Generate a UUID v4** for the UID field: `<uuid4>@claude.ai`
5. **Set DTSTAMP** to the current UTC timestamp
6. **Build VEVENT block(s)** with all applicable properties
7. **Add VALARM** for reminders (default: 15 minutes before if not specified)
8. **Add RRULE** for recurring events
9. **Wrap in VCALENDAR** with standard headers
10. **Write** the `.ics` file to the current working directory and **open** it with `open <filename>.ics`

## Defaults

- **Timezone**: `America/New_York` (Eastern) — do NOT ask the user for timezone unless the event is clearly in another zone
- **Auto-open**: Always run `open <filename>.ics` after writing the file
- **Save location**: Current working directory
- **Duration**: 1 hour if not specified
- **Reminder**: 15 minutes before if not specified
- **Filename**: kebab-case from the event summary, e.g., `team-meeting.ics`

## VCALENDAR Wrapper

Every `.ics` file starts and ends with:
```
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Claude//ICS Generator//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
<VTIMEZONE blocks>
<VEVENT blocks>
END:VCALENDAR
```

## Date/Time Formats

### Timed events (with timezone)
```
DTSTART;TZID=America/New_York:20250115T140000
DTEND;TZID=America/New_York:20250115T150000
```

### All-day events (DATE only, no time component)
```
DTSTART;VALUE=DATE:20250115
DTEND;VALUE=DATE:20250116
```
Note: DTEND for all-day events is **exclusive** — a single all-day event on Jan 15 uses DTEND of Jan 16.

### UTC times
```
DTSTART:20250115T190000Z
```

## Event Properties

### Required
| Property | Description | Example |
|----------|-------------|---------|
| `DTSTART` | Start date/time | `DTSTART;TZID=America/New_York:20250115T140000` |
| `DTEND` or `DURATION` | End time or duration | `DTEND;TZID=America/New_York:20250115T150000` or `DURATION:PT1H` |
| `SUMMARY` | Event title | `SUMMARY:Team Standup` |
| `UID` | Unique identifier | `UID:[email protected]` |
| `DTSTAMP` | Creation timestamp (UTC) | `DTSTAMP:20250115T120000Z` |

### Optional
| Property | Description | Example |
|----------|-------------|---------|
| `DESCRIPTION` | Event details/notes | `DESCRIPTION:Discuss Q1 roadmap` |
| `LOCATION` | Event location | `LOCATION:Conference Room A` |
| `URL` | Related link | `URL:https://meet.google.com/abc-defg-hij` |
| `ORGANIZER` | Event organizer | `ORGANIZER;CN=John:mailto:[email protected]` |
| `ATTENDEE` | Invited person | `ATTENDEE;ROLE=REQ-PARTICIPANT;RSVP=TRUE;CN=Jane:mailto:[email protected]` |
| `STATUS` | Event status | `STATUS:CONFIRMED` (or `TENTATIVE`, `CANCELLED`) |
| `TRANSP` | Time transparency | `TRANSP:OPAQUE` (busy) or `TRANSP:TRANSPARENT` (free) |
| `CATEGORIES` | Event categories | `CATEGORIES:MEETING,WORK` |
| `PRIORITY` | Priority (0-9) | `PRIORITY:1` (1=highest, 9=lowest, 0=undefined) |

### DURATION format
```
DURATION:PT1H          → 1 hour
DURATION:PT30M         → 30 minutes
DURATION:PT1H30M       → 1 hour 30 minutes
DURATION:P1D           → 1 day
DURATION:P1W           → 1 week
```

## Text Escaping

Escape these characters in text property values:
- Backslash: `\\`
- Semicolon: `\;`
- Comma: `\,`
- Newline: `\n`

Example:
```
DESCRIPTION:Agenda:\n1. Review\n2. Planning\nLocation: Room 4\, Building A
```

## Reminders (VALARM)

Add inside a VEVENT block:
```
BEGIN:VALARM
TRIGGER:-PT15M
ACTION:DISPLAY
DESCRIPTION:Reminder
END:VALARM
```

### Common trigger durations
| Natural language | TRIGGER value |
|-----------------|---------------|
| At time of event | `TRIGGER:PT0S` |
| 5 minutes before | `TRIGGER:-PT5M` |
| 10 minutes before | `TRIGGER:-PT10M` |
| 15 minutes before | `TRIGGER:-PT15M` |
| 30 minutes before | `TRIGGER:-PT30M` |
| 1 hour before | `TRIGGER:-PT1H` |
| 2 hours before | `TRIGGER:-PT2H` |
| 1 day before | `TRIGGER:-P1D` |
| 1 week before | `TRIGGER:-P1W` |

## Recurring Events (RRULE)

Add an RRULE property to the VEVENT:
```
RRULE:FREQ=WEEKLY;BYDAY=TU,TH;COUNT=10
```

### Common patterns
| Pattern | RRULE |
|---------|-------|
| Every day | `RRULE:FREQ=DAILY` |
| Every weekday | `RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR` |
| Every week | `RRULE:FREQ=WEEKLY` |
| Every 2 weeks | `RRULE:FREQ=WEEKLY;INTERVAL=2` |
| Every month (same date) | `RRULE:FREQ=MONTHLY` |
| Every month (e.g., 2nd Tuesday) | `RRULE:FREQ=MONTHLY;BYDAY=2TU` |
| Every year | `RRULE:FREQ=YEARLY` |
| Weekly until a date | `RRULE:FREQ=WEEKLY;UNTIL=20250630T235959Z` |
| Weekly for 10 occurrences | `RRULE:FREQ=WEEKLY;COUNT=10` |

### Excluding dates (EXDATE)
```
EXDATE;TZID=America/New_York:20250219T140000
EXDATE;TZID=America/New_York:20250226T140000
```

## Timezone Handling

### Default: America/New_York

Always include this VTIMEZONE block when using Eastern time:
```
BEGIN:VTIMEZONE
TZID:America/New_York
BEGIN:STANDARD
DTSTART:19701101T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=11
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19700308T020000
RRULE:FREQ=YEARLY;BYDAY=2SU;BYMONTH=3
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONE
```

### Common timezone name mapping
| User says | TZID |
|-----------|------|
| Eastern, ET, EST, EDT | `America/New_York` |
| Central, CT, CST, CDT | `America/Chicago` |
| Mountain, MT, MST, MDT | `America/Denver` |
| Pacific, PT, PST, PDT | `America/Los_Angeles` |
| Arizona | `America/Phoenix` |
| Hawaii, HST | `Pacific/Honolulu` |
| London, GMT, BST | `Europe/London` |
| Paris, CET, CEST | `Europe/Paris` |
| Tokyo, JST | `Asia/Tokyo` |

See [references/ics-format.md](references/ics-format.md) for full VTIMEZONE definitions for all common timezones.

## Line Folding

Lines longer than 75 octets MUST be folded by inserting a CRLF followed by a single whitespace character (space or tab). In practice, keep property lines under 75 characters when possible.

```
DESCRIPTION:This is a very long description that would exceed the seventy-f
 ive octet limit so it is folded onto the next line with a leading space.
```

## Key Gotchas

1. **Line endings**: Use CRLF (`\r\n`) line endings throughout the file
2. **DTEND is exclusive**: An all-day event on Jan 15 needs `DTEND;VALUE=DATE:20250116`
3. **UID must be globally unique**: Always generate a fresh UUID v4 for each event
4. **DTSTAMP is required**: Always set to current UTC time
5. **VTIMEZONE must precede VEVENT**: Place timezone definitions before events in the file
6. **No trailing whitespace**: Lines must not end with spaces or tabs
7. **Property names are case-insensitive** but conventionally UPPERCASE
8. **Empty lines**: No blank lines allowed between properties within a component
9. **UNTIL in RRULE must be UTC**: `UNTIL=20250630T235959Z` (with Z suffix)
10. **Multi-value properties**: Use comma separation: `EXDATE;TZID=America/New_York:20250219T140000,20250226T140000`

## Complete Examples

### Simple meeting
```
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Claude//ICS Generator//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VTIMEZONE
TZID:America/New_York
BEGIN:STANDARD
DTSTART:19701101T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=11
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLI