Initial commit

skills/timezone-tools/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: timezone-tools
+description: Get current time in any timezone and convert times between timezones. Use when working with time, dates, timezones, scheduling across regions, or when user mentions specific cities/regions for time queries. Supports IANA timezone names.
+---
+
+# Timezone Tools
+
+Get current time in any timezone and convert times between different timezones using IANA timezone database.
+
+## Quick Start
+
+### Get current time in a timezone
+
+```bash
+python scripts/get_time.py "America/New_York"
+```
+
+### Convert time between timezones
+
+```bash
+python scripts/convert_time.py "America/New_York" "14:30" "Australia/Perth"
+```
+
+### Search for timezone names
+
+```bash
+python scripts/list_timezones.py "perth"
+```
+
+## Instructions
+
+When the user asks about time or timezones:
+
+1. **For current time queries** (e.g., "What time is it in Tokyo?"):
+   - Use `get_time.py` with IANA timezone name
+   - If unsure of timezone name, search first with `list_timezones.py`
+   - Script outputs: timezone, datetime, day of week, DST status
+
+2. **For time conversions** (e.g., "What's 2pm EST in Perth time?"):
+   - Use `convert_time.py` with source timezone, time (HH:MM 24-hour), target timezone
+   - Script shows source time, target time, and time difference
+   - Automatically handles DST changes
+
+3. **For timezone searches**:
+   - Use `list_timezones.py` with city/country name
+   - Returns matching IANA timezone names
+
+## Common Timezones Reference
+
+For quick reference, see [data/common_timezones.json](data/common_timezones.json) which includes major cities worldwide, with Perth prominently featured.
+
+**User's local timezone**: The scripts automatically detect your local timezone using `tzlocal`.
+
+## Examples
+
+### Example 1: Current time query
+
+User: "What time is it in Perth?"
+
+```bash
+python scripts/list_timezones.py "perth"
+# Output: Australia/Perth
+
+python scripts/get_time.py "Australia/Perth"
+# Output:
+# Timezone: Australia/Perth
+# Current time: 2025-11-07T15:30:45
+# Day: Thursday
+# DST: No
+```
+
+### Example 2: Time conversion
+
+User: "I have a meeting at 2pm New York time, what time is that in Perth?"
+
+```bash
+python scripts/convert_time.py "America/New_York" "14:00" "Australia/Perth"
+# Output:
+# Source: America/New_York - 2025-11-07T14:00:00 (Thursday, DST: No)
+# Target: Australia/Perth - 2025-11-08T03:00:00 (Friday, DST: No)
+# Time difference: +13.0h
+```
+
+### Example 3: Multiple timezone search
+
+User: "What are the timezone codes for London, Tokyo, and Sydney?"
+
+```bash
+python scripts/list_timezones.py "london"
+python scripts/list_timezones.py "tokyo"
+python scripts/list_timezones.py "sydney"
+# Outputs:
+# Europe/London
+# Asia/Tokyo
+# Australia/Sydney
+```
+
+## Time Format
+
+- All times use **24-hour format** (HH:MM): `14:30` not `2:30 PM`
+- ISO 8601 datetime format for output: `2025-11-07T14:30:45`
+- IANA timezone names (e.g., `America/New_York`, not `EST`)
+
+## Troubleshooting
+
+### "Invalid timezone" error
+
+- Use IANA timezone names: `America/New_York` not `EST` or `Eastern`
+- Search with `list_timezones.py` if unsure
+- Check [data/common_timezones.json](data/common_timezones.json) for reference
+
+### "Invalid time format" error
+
+- Use 24-hour format: `14:30` not `2:30 PM`
+- Format must be `HH:MM` with colon separator
+
+### Missing dependencies
+
+Install required Python packages:
+
+```bash
+pip install tzlocal
+```
+
+## Dependencies
+
+- Python 3.9+
+- `tzlocal>=5.0` - for local timezone detection
+- `zoneinfo` - built-in Python 3.9+ (IANA timezone database)
+
+## Notes
+
+- Scripts automatically handle Daylight Saving Time (DST)
+- Local timezone is auto-detected from system
+- All timezone data uses IANA Time Zone Database
+- Perth, Australia timezone: `Australia/Perth` (UTC+8, no DST)