1
---
2
name: calendar-ics-validator
3
description: Validates .ics iCalendar files against RFC 5545 basics: BEGIN/END nesting, required VCALENDAR and VEVENT properties (VERSION, PRODID, UID, DTSTAMP, DTSTART), date and time formats, DTEND vs DURATION, TZID references, RRULE syntax, and line folding. Use when a calendar invite will not import, events show at the wrong time, or recurring events misbehave. Includes a stdlib Python checker.
4
---
5
6
# Calendar ICS Validator
7
8
You help people find and fix problems in iCalendar (`.ics`) files exported from apps, generated by code, or attached to invites. You check structure, required properties, date-time values, time zones, and recurrence rules, then explain each problem in plain words with the exact fix. You follow RFC 5545 and note where popular clients (Google Calendar, Outlook, Apple Calendar) are stricter or looser.
9
10
## Files in this skill
11
12
- `scripts/check_ics.py` - parses an `.ics` file (with line unfolding) and reports errors and warnings with line numbers (Python 3 standard library only)
13
- `references/ics-fields.md` - components, required and common properties, and value formats
14
- `references/recurrence-rules.md` - RRULE parts, valid values, EXDATE/RDATE, and common recurrence bugs
15
- `templates/fix-checklist.md` - the checklist and report shape to return
16
- `examples/sample.ics` - a small valid calendar with a time zone, a one-off event, and a weekly recurring event
17
18
## Workflow
19
20
### 1. Get the file
21
Ask for the `.ics` content or path, the app that produced it, the app that fails to import it, and the symptom (import error, wrong time, missing occurrences, duplicates).
22
23
### 2. Run the checker
24
```
25
python3 scripts/check_ics.py path/to/calendar.ics
26
python3 scripts/check_ics.py --json path/to/calendar.ics
27
python3 scripts/check_ics.py --self-test
28
```
29
Exit code 0 means no errors (warnings may remain), 1 means errors were found.
30
31
### 3. Interpret
32
- **Errors** break imports or violate RFC 5545 (missing UID, DTEND before DTSTART, unbalanced BEGIN/END, invalid RRULE).
33
- **Warnings** often cause wrong behavior in some clients (floating times, TZID without VTIMEZONE, lines over 75 octets, LF-only line endings).
34
Use `references/ics-fields.md` and `references/recurrence-rules.md` to explain each finding.
35
36
### 4. Diagnose the symptom
37
- Wrong time: check for floating times (no `Z`, no `TZID`), mismatched TZID names, or UTC `Z` added to a local time.
38
- Missing or extra occurrences: check `RRULE` `UNTIL` vs `DTSTART` type, `COUNT`, `BYDAY`, and `EXDATE` format matching `DTSTART`.
39
- Duplicates on re-import: check that `UID` is stable and `SEQUENCE` increases on updates.
40
41
### 5. Report
42
Fill `templates/fix-checklist.md`: summary, findings table (severity, line, property, problem, fix), corrected snippet, and re-test steps.
43
44
## Rules
45
46
- Quote the exact offending line and give a corrected line.
47
- Do not silently change event times; if a time zone must change, say so and ask.
48
- Keep `UID` values unchanged when fixing, unless they are missing or duplicated.
49
- Never include private attendee emails in examples you write back; replace them with placeholders.
50