Skald-Circle/skills/ics2json/SKILL.md

name, description

name

description

ics2json

Download an iCalendar (ICS) feed from a URL and output structured JSON with all events. Use this skill whenever the user needs to read, analyze, or integrate events from a public iCal feed such as Teamup or Google Calendar, especially when no API keys are available. Also use as the base for cron jobs that periodically analyze a calendar feed. If the user mentions an .ics file or calendar feed, use this skill.

ics2json

Updated: 2026-06-08

Downloads an iCalendar (ICS) feed from a URL and outputs structured JSON with all events.

When to use

• Reading and analyzing events from a public iCal feed (Teamup, Google Calendar, etc.)
• Integrating an external calendar without API keys
• As the base for cron jobs that periodically analyze a feed

Script

python3 skills/ics2json/ics2json.py <url> [options]

Options

Flag	Description
--days N	Only events starting within the next N days
--all	Include past events (default: future or ongoing only)
--pretty	Pretty-print JSON output (default: compact, single-line)
--meta	Only output calendar metadata (name, description, event count). No events returned.

Output JSON format

{
  "calendar": "Calendar name",
  "description": "Calendar description",
  "feed_url": "Feed URL",
  "fetched_at": "2026-05-20T12:00:00+01:00",
  "total_events": 5,
  "events": [
    {
      "uid": "TU123456",
      "title": "Event title",
      "description": "Description...",
      "location": "Venue",
      "where": "Teamup address",
      "categories": "kink oriented event ⛓️",
      "event_url": "https://teamup.com/...",
      "external_url": "https://tickets.example.com",
      "start": "2026-05-20T19:00:00+01:00",
      "end": "2026-05-20T23:00:00+01:00",
      "created": "2026-05-01T10:00:00+00:00",
      "last_modified": null,
      "stamp": "2026-05-19T13:18:47+00:00",
      "attachments": [{"url": "https://...", "type": "image/jpeg", "filename": "flyer.jpg"}]
    }
  ]
}

Examples

# Download a Teamup feed, future events only (compact output)
python3 skills/ics2json/ics2json.py https://ics.teamup.com/feed/ksmt7zqvai72zisjo4/12645979.ics

# Metadata only (compact)
python3 skills/ics2json/ics2json.py https://ics.teamup.com/feed/ksmt7zqvai72zisjo4/12645979.ics --meta

# Only the next 30 days (compact)
python3 skills/ics2json/ics2json.py https://ics.teamup.com/feed/ksmt7zqvai72zisjo4/12645979.ics --days 30

# All events (including past), pretty-printed for human reading
python3 skills/ics2json/ics2json.py https://ics.teamup.com/feed/ksmt7zqvai72zisjo4/12645979.ics --all --pretty