Skill: tobewin/timezone-helper (version 1.0.0)

--- name: timezone-helper description: Time zone conversion, world clock, and meeting planner. Use when the user asks about current time in a city, needs to convert time between zones, wants to schedule a meeting across multiple time zones, or asks about daylight saving time (DST). Built-in IANA timezone data for 200+ cities. No API key, no scripts, no Python required — fully offline. version: 1.0.0 license: MIT-0 metadata: openclaw: emoji: "🌍" --- # Timezone Helper Convert times between any time zones, plan global meetings, check DST status. Zero dependencies — all data built-in, works in any environment. Full city-to-timezone mapping: see `references/cities.md`. ## When to use - "What time is it in Tokyo right now?" - "Convert 3pm New York to London time" - "Schedule a meeting for our team in SF, London and Singapore" - "Does Germany observe DST? When does it change?" - "What's the UTC offset for IST?" - "Find a time that works for NYC, Berlin and Beijing" --- ## Core concepts ### UTC offset Every timezone is expressed as UTC±HH:MM. - UTC+9 = 9 hours ahead of UTC (Tokyo, Seoul) - UTC-5 = 5 hours behind UTC (New York EST, Lima) - UTC+0 = same as UTC (London GMT, Reykjavik) ### DST (Daylight Saving Time) Some regions shift clocks ±1 hour seasonally: - **Northern Hemisphere** (US, Europe, etc.): spring forward, fall back - US: second Sunday March → first Sunday November - EU: last Sunday March → last Sunday October - **Southern Hemisphere** (Australia, NZ, etc.): opposite — DST in Oct–Apr - **No DST**: China, Japan, India, most of Africa, Middle East, Southeast Asia Always confirm the current date when doing DST-sensitive conversions. --- ## Step 1: Resolve city/region to IANA timezone Use the table in `references/cities.md` to map user input to an IANA zone. Common shortcuts to recognize: ``` EST / ET → America/New_York (UTC-5 standard, UTC-4 DST) CST (US) → America/Chicago (UTC-6 standard, UTC-5 DST) MST → America/Denver (UTC-7 standard, UTC-6 DST) PST / PT → America/Los_Angeles (UTC-8 standard, UTC-7 DST) GMT / UTC → UTC (UTC+0, no DST) BST → Europe/London (UTC+1, summer only) CET / CEST → Europe/Paris (UTC+1 standard, UTC+2 DST) IST → Asia/Kolkata (UTC+5:30, no DST) CST (China) → Asia/Shanghai (UTC+8, no DST) JST → Asia/Tokyo (UTC+9, no DST) AEST / AEDT → Australia/Sydney (UTC+10 standard, UTC+11 DST) ``` --- ## Step 2: Apply UTC offset Conversion formula: ``` Target time = Source time + (Target UTC offset) - (Source UTC offset) ``` If result crosses midnight: adjust date ±1 day accordingly. Example: ``` Convert 14:00 New York (EST, UTC-5) → Tokyo (JST, UTC+9) Difference = +9 - (-5) = +14 hours 14:00 + 14h = 28:00 → 04:00 next day Tokyo ``` --- ## Step 3: Check DST status Before finalizing, verify whether DST is currently active for each zone. If the user's current date is near a DST transition, note the change. DST transitions (approximate): ``` US (spring forward): Second Sunday of March, 02:00 → 03:00 US (fall back): First Sunday of November, 02:00 → 01:00 EU (spring forward): Last Sunday of March, 01:00 UTC → 02:00 UTC EU (fall back): Last Sunday of October, 01:00 UTC → 00:00 UTC Australia/Sydney: First Sunday of October, 02:00 → 03:00 Australia/Sydney: First Sunday of April, 03:00 → 02:00 ``` --- ## Output formats ### Single conversion ``` 🌍 Time Zone Conversion ━━━━━━━━━━━━━━━━━━━━ Source: 3:00 PM Wed, Mar 20 — New York (EST, UTC-5) Target: 8:00 PM Wed, Mar 20 — London (GMT, UTC+0) 4:00 AM Thu, Mar 21 — Tokyo (JST, UTC+9) 1:00 AM Thu, Mar 21 — Singapore (SGT, UTC+8) ``` ### World clock (current time) ``` 🕐 Current World Time (based on: 15:00 UTC) ━━━━━━━━━━━━━━━━━━━━ 🇺🇸 New York 10:00 AM Wed (EST, UTC-5) 🇬🇧 London 15:00 Wed (GMT, UTC+0) 🇩🇪 Berlin 16:00 Wed (CET, UTC+1) 🇮🇳 Mumbai 20:30 Wed (IST, UTC+5:30) 🇨🇳 Beijing 23:00 Wed (CST, UTC+8) 🇯🇵 Tokyo 00:00 Thu (JST, UTC+9) 🇦🇺 Sydney 02:00 Thu (AEDT, UTC+11) ``` ### Meeting planner ``` 📅 Meeting Planner ━━━━━━━━━━━━━━━━━━━━ Participants: San Francisco / London / Singapore Option A — Best for SF + London: San Francisco 09:00 AM (PST, UTC-8) ✅ work hours London 17:00 (GMT, UTC+0) ✅ end of day Singapore 01:00 AM (SGT, UTC+8) ❌ midnight Option B — Best for London + Singapore: San Francisco 01:00 AM (PST, UTC-8) ❌ midnight London 09:00 (GMT, UTC+0) ✅ work hours Singapore 17:00 (SGT, UTC+8) ✅ work hours No perfect overlap exists. Recommended compromise: San Francisco 06:00 AM ⚠️ early London 14:00 ✅ Singapore 22:00 ⚠️ late evening ``` ### DST query ``` 🕐 DST Information: Germany (Europe/Berlin) ━━━━━━━━━━━━━━━━━━━━ Current offset: UTC+1 (CET — Central European Time) DST observed: Yes DST offset: UTC+2 (CEST — Central European Summer Time) Spring forward: Last Sunday of March → clocks +1h at 02:00 Fall back: Last Sunday of October → clocks -1h at 03:00 2026 transitions: Mar 29 (→ CEST) / Oct 25 (→ CET) ``` --- ## Meeting planner logic When finding meeting overlap across zones: ``` 1. Define "work hours" as 09:00–18:00 local time 2. Define "acceptable" as 07:00–21:00 local time 3. Convert each hour of the day to all participants' local times 4. Score each UTC hour: - All in work hours → ✅ ideal - All in acceptable → ⚠️ workable - Any outside 07-21 → ❌ avoid 5. Present top 2-3 options with clear local times 6. If no ideal slot exists, say so explicitly and suggest best compromise ``` --- ## Notes - Always ask for or confirm the current date when DST status matters - "IST" is ambiguous: could be India (UTC+5:30), Israel (UTC+2), or Ireland (UTC+0/+1) — clarify with user if context is unclear - "CST" is ambiguous: US Central (UTC-6/-5) or China Standard (UTC+8) — resolve from context - Half-hour and 45-minute offsets exist: India (UTC+5:30), Iran (UTC+3:30), Nepal (UTC+5:45), Australia/Lord Howe (UTC+10:30/+11) - For precise current-time queries, note that this skill provides static offset data; the actual current time depends on the system clock

path: LICENSE.txt
content: MIT No Attribution (MIT-0)

Copyright 2026 ToBeWin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED.


path: references/cities.md
content: # City to IANA Timezone Mapping

200+ major cities worldwide. Format: City / Region — IANA Zone — Standard Offset — DST offset (if applicable)

## Americas

### United States
```
New York, Miami, Boston, Atlanta, Detroit, Philadelphia    America/New_York      UTC-5  / UTC-4 (DST)
Chicago, Dallas, Houston, Minneapolis, Kansas City         America/Chicago       UTC-6  / UTC-5 (DST)
Denver, Salt Lake City, Phoenix (no DST)                   America/Denver        UTC-7  / UTC-6 (DST)
  Phoenix specifically:                                    America/Phoenix       UTC-7  (no DST)
Los Angeles, San Francisco, Seattle, Portland, Las Vegas   America/Los_Angeles   UTC-8  / UTC-7 (DST)
Anchorage                                                  America/Anchorage     UTC-9  / UTC-8 (DST)
Honolulu                                                   Pacific/Honolulu      UTC-10 (no DST)
```

### Canada
```
Toronto, Ottawa, Montreal, Quebec City                     America/Toronto       UTC-5  / UTC-4 (DST)
Winnipeg, Regina (no DST), Saskatoon (no DST)              America/Winnipeg      UTC-6  / UTC-5 (DST)
  Regina/Saskatoon specifically:                           America/Regina        UTC-6  (no DST)
Calgary, Edmonton                                          America/Edmonton      UTC-7  / UTC-6 (DST)
Vancouver, Victoria                                        America/Vancouver     UTC-8  / UTC-7 (DST)
Halifax                                                    America/Halifax       UTC-4  / UTC-3 (DST)
St. John's                                                 America/St_Johns      UTC-3:30 / UTC-2:30 (DST)
```

### Latin America
```
Mexico City, Guadalajara, Monterrey                        America/Mexico_City   UTC-6  / UTC-5 (DST)
Tijuana                                                    America/Tijuana       UTC-8  / UTC-7 (DST)
Guatemala City                                             America/Guatemala     UTC-6  (no DST)
San José (Costa Rica)                                      America/Costa_Rica    UTC-6  (no DST)
Panama City                                                America/Panama        UTC-5  (no DST)
Bogotá                                                     America/Bogota        UTC-5  (no DST)
Lima                                                       America/Lima          UTC-5  (no DST)
Quito                                                      America/Guayaquil     UTC-5  (no DST)
Caracas                                                    America/Caracas       UTC-4  (no DST)
La Paz                                                     America/La_Paz        UTC-4  (no DST)
Santiago                                                   America/Santiago      UTC-3  / UTC-4 (DST, Southern Hemisphere)
Buenos Aires                                               America/Argentina/Buenos_Aires  UTC-3  (no DST)
São Paulo, Rio de Janeiro                                  America/Sao_Paulo     UTC-3  (no DST, DST suspended since 2019)
Montevideo                                                 America/Montevideo    UTC-3  (no DST)
Asunción                                                   America/Asuncion      UTC-4  / UTC-3 (DST)
Havana                                                     America/Havana        UTC-5  / UTC-4 (DST)
Santo Domingo                                              America/Santo_Domingo UTC-4  (no DST)
```

## Europe

### Western Europe
```
London, Dublin                                             Europe/London         UTC+0  / UTC+1 (BST, DST)
Lisbon                                                     Europe/Lisbon         UTC+0  / UTC+1 (DST)
Madrid, Barcelona                                          Europe/Madrid         UTC+1  / UTC+2 (DST)
Paris, Lyon, Marseille                                     Europe/Paris          UTC+1  / UTC+2 (DST)
Amsterdam, Rotterdam                                       Europe/Amsterdam      UTC+1  / UTC+2 (DST)
Brussels                                                   Europe/Brussels       UTC+1  / UTC+2 (DST)
Bern, Zurich, Geneva                                       Europe/Zurich         UTC+1  / UTC+2 (DST)
Rome, Milan                                                Europe/Rome           UTC+1  / UTC+2 (DST)
Berlin, Frankfurt, Hamburg, Munich                         Europe/Berlin         UTC+1  / UTC+2 (DST)
Vienna                                                     Europe/Vienna         UTC+1  / UTC+2 (DST)
Prague                                                     Europe/Prague         UTC+1  / UTC+2 (DST)
Warsaw                                                     Europe/Warsaw         UTC+1  / UTC+2 (DST)
Copenhagen                                                 Europe/Copenhagen     UTC+1  / UTC+2 (DST)
Stockholm                                                  Europe/Stockholm      UTC+1  / UTC+2 (DST)
Oslo                                                       Europe/Oslo           UTC+1  / UTC+2 (DST)
Helsinki                                                   Europe/Helsinki       UTC+2  / UTC+3 (DST)
Athens                                                     Europe/Athens         UTC+2  / UTC+3 (DST)
Bucharest                                                  Europe/Bucharest      UTC+2  / UTC+3 (DST)
Sofia                                                      Europe/Sofia          UTC+2  / UTC+3 (DST)
Kyiv                                                       Europe/Kyiv           UTC+2  / UTC+3 (DST)
Reykjavik                                                  Atlantic/Reykjavik    UTC+0  (no DST)
```

### Eastern Europe & Russia
```
Moscow, St. Petersburg, Yekaterinburg (western Russia)     Europe/Moscow         UTC+3  (no DST since 2014)
Novosibirsk                                                Asia/Novosibirsk      UTC+7  (no DST)
Krasnoyarsk                                                Asia/Krasnoyarsk      UTC+7  (no DST)
Irkutsk                                                    Asia/Irkutsk          UTC+8  (no DST)
Yakutsk                                                    Asia/Yakutsk          UTC+9  (no DST)
Vladivostok                                                Asia/Vladivostok      UTC+10 (no DST)
Kamchatka                                                  Asia/Kamchatka        UTC+12 (no DST)
Minsk                                                      Europe/Minsk          UTC+3  (no DST)
Istanbul                                                   Europe/Istanbul       UTC+3  (no DST since 2016)
```

## Middle East & Africa

### Middle East
```
Dubai, Abu Dhabi                                           Asia/Dubai            UTC+4  (no DST)
Riyadh, Jeddah                                             Asia/Riyadh           UTC+3  (no DST)
Kuwait City                                                Asia/Kuwait           UTC+3  (no DST)
Doha                                                       Asia/Qatar            UTC+3  (no DST)
Manama (Bahrain)                                           Asia/Bahrain          UTC+3  (no DST)
Muscat                                                     Asia/Muscat           UTC+4  (no DST)
Tehran                                                     Asia/Tehran           UTC+3:30 / UTC+4:30 (DST)
Baghdad                                                    Asia/Baghdad          UTC+3  (no DST)
Amman                                                      Asia/Amman            UTC+2  / UTC+3 (DST)
Beirut                                                     Asia/Beirut           UTC+2  / UTC+3 (DST)
Jerusalem, Tel Aviv                                        Asia/Jerusalem        UTC+2  / UTC+3 (DST)
Aden (Yemen)                                               Asia/Aden             UTC+3  (no DST)
Sana'a                                                     Asia/Aden             UTC+3  (no DST)
```

### Africa
```
Cairo                                                      Africa/Cairo          UTC+2  (no DST since 2011)
Casablanca                                                 Africa/Casablanca     UTC+1  (no DST)
Tunis                                                      Africa/Tunis          UTC+1  (no DST)
Algiers                                                    Africa/Algiers        UTC+1  (no DST)
Lagos, Abuja                                               Africa/Lagos          UTC+1  (no DST)
Nairobi                                                    Africa/Nairobi        UTC+3  (no DST)
Addis Ababa                                                Africa/Addis_Ababa    UTC+3  (no DST)
Johannesburg, Cape Town                                    Africa/Johannesburg   UTC+2  (no DST)
Accra                                                      Africa/Accra          UTC+0  (no DST)
Dar es Salaam                                              Africa/Dar_es_Salaam  UTC+3  (no DST)
Khartoum                                                   Africa/Khartoum       UTC+3  (no DST)
Kinshasa (DRC west)                                        Africa/Kinshasa       UTC+1  (no DST)
Lusaka                                                     Africa/Lusaka         UTC+2  (no DST)
Harare                                                     Africa/Harare         UTC+2  (no DST)
```

## Asia & Pacific

### South Asia
```
Mumbai, Delhi, Bangalore, Chennai, Kolkata, Hyderabad      Asia/Kolkata          UTC+5:30 (no DST)
Karachi, Lahore, Islamabad                                 Asia/Karachi          UTC+5   (no DST)
Dhaka                                                      Asia/Dhaka            UTC+6   (no DST)
Kathmandu                                                  Asia/Kathmandu        UTC+5:45 (no DST)
Colombo                                                    Asia/Colombo          UTC+5:30 (no DST)
Kabul                                                      Asia/Kabul            UTC+4:30 (no DST)
```

### Southeast Asia
```
Bangkok, Hanoi, Ho Chi Minh City, Vientiane, Phnom Penh   Asia/Bangkok          UTC+7   (no DST)
Jakarta, Surabaya, Bandung                                 Asia/Jakarta          UTC+7   (no DST)
Kuala Lumpur, Penang                                       Asia/Kuala_Lumpur     UTC+8   (no DST)
Singapore                                                  Asia/Singapore        UTC+8   (no DST)
Manila                                                     Asia/Manila           UTC+8   (no DST)
Yangon (Rangoon)                                           Asia/Rangoon          UTC+6:30 (no DST)
Phnom Penh                                                 Asia/Phnom_Penh       UTC+7   (no DST)
Taipei                                                     Asia/Taipei           UTC+8   (no DST)
Bali (Denpasar)                                            Asia/Makassar         UTC+8   (no DST)
```

### East Asia
```
Beijing, Shanghai, Chongqing, Guangzhou, Shenzhen          Asia/Shanghai         UTC+8   (no DST)
Hong Kong                                                  Asia/Hong_Kong        UTC+8   (no DST)
Macau                                                      Asia/Macau            UTC+8   (no DST)
Taipei                                                     Asia/Taipei           UTC+8   (no DST)
Seoul, Busan                                               Asia/Seoul            UTC+9   (no DST)
Tokyo, Osaka, Kyoto, Nagoya, Sapporo                       Asia/Tokyo            UTC+9   (no DST)
Ulaanbaatar                                                Asia/Ulaanbaatar      UTC+8   (no DST)
Pyongyang                                                  Asia/Pyongyang        UTC+9   (no DST)
```

### Central Asia
```
Tashkent                                                   Asia/Tashkent         UTC+5   (no DST)
Almaty                                                     Asia/Almaty           UTC+6   (no DST)
Astana (Nur-Sultan)                                        Asia/Almaty           UTC+6   (no DST)
Bishkek                                                    Asia/Bishkek          UTC+6   (no DST)
Dushanbe                                                   Asia/Dushanbe         UTC+5   (no DST)
Ashgabat                                                   Asia/Ashgabat         UTC+5   (no DST)
Baku                                                       Asia/Baku             UTC+4   / UTC+5 (DST)
Tbilisi                                                    Asia/Tbilisi          UTC+4   (no DST)
Yerevan                                                    Asia/Yerevan          UTC+4   (no DST)
```

### Pacific
```
Sydney, Melbourne, Canberra, Brisbane (no DST)             Australia/Sydney      UTC+10  / UTC+11 (AEDT, DST)
  Brisbane specifically:                                   Australia/Brisbane    UTC+10  (no DST)
Adelaide                                                   Australia/Adelaide    UTC+9:30 / UTC+10:30 (DST)
Perth                                                      Australia/Perth       UTC+8   (no DST)
Darwin                                                     Australia/Darwin      UTC+9:30 (no DST)
Hobart                                                     Australia/Hobart      UTC+10  / UTC+11 (DST)
Auckland, Wellington                                       Pacific/Auckland      UTC+12  / UTC+13 (DST, Southern Hemisphere)
Fiji                                                       Pacific/Fiji          UTC+12  / UTC+13 (DST)
Honolulu (Hawaii)                                          Pacific/Honolulu      UTC-10  (no DST)
Guam                                                       Pacific/Guam          UTC+10  (no DST)
```

---

## UTC Offset Quick Reference

```
UTC-12   Baker Island (uninhabited)
UTC-11   Pago Pago (American Samoa)
UTC-10   Honolulu
UTC-9    Anchorage
UTC-8    Los Angeles, Vancouver, Tijuana
UTC-7    Denver, Phoenix
UTC-6    Chicago, Mexico City, Guatemala City
UTC-5    New York, Toronto, Lima, Bogotá, Panama
UTC-4    Halifax, Caracas, La Paz
UTC-3:30 St. John's
UTC-3    Buenos Aires, São Paulo, Montevideo, Santiago (winter)
UTC-2    South Georgia Island
UTC-1    Azores, Cape Verde
UTC+0    London (winter), Dublin, Reykjavik, Accra
UTC+1    Paris, Berlin, Rome, Madrid, Warsaw, Lagos
UTC+2    Cairo, Helsinki, Athens, Johannesburg, Kyiv
UTC+3    Moscow, Nairobi, Riyadh, Istanbul
UTC+3:30 Tehran (winter)
UTC+4    Dubai, Baku, Tbilisi
UTC+4:30 Kabul
UTC+5    Karachi, Tashkent
UTC+5:30 Mumbai, Delhi, Colombo
UTC+5:45 Kathmandu
UTC+6    Dhaka, Almaty
UTC+6:30 Yangon
UTC+7    Bangkok, Jakarta, Hanoi
UTC+8    Beijing, Singapore, Hong Kong, Manila, Perth, Taipei
UTC+9    Tokyo, Seoul
UTC+9:30 Adelaide (winter), Darwin
UTC+10   Sydney (winter), Brisbane, Guam
UTC+10:30 Lord Howe Island
UTC+11   Sydney (summer), Solomon Islands
UTC+12   Auckland (winter), Fiji
UTC+13   Auckland (summer)
UTC+14   Kiribati (Line Islands)
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)