Time & Timezone Helper Skill

Ultra-efficient, cross-platform time operations using native PHP. Replaces timezone MCP servers with 67% token savings.

Overview

This skill provides timezone and time operations WITHOUT requiring MCP servers, saving 60-75% tokens per query.

Cross-Platform: Works on Windows, Mac, and Linux (uses PHP, not bash scripts).

Token Savings:

MCP call: ~400 tokens
This skill: ~130 tokens
Savings: 270 tokens per query (67.5%)

🔧 BASH COMMAND ATTRIBUTION PATTERN

CRITICAL: Before executing EACH php/bash command, MUST output:

🔧 [time-helper] Running: <command>

Examples:

🔧 [time-helper] Running: php -r "echo (new DateTime('now', new DateTimeZone('Asia/Tokyo')))->format('Y-m-d H:i:s T');"
🔧 [time-helper] Running: php -r "date_default_timezone_set('America/New_York'); echo date('Y-m-d H:i:s T');"
🔧 [time-helper] Running: bash .claude/skills/colored-output/color.sh skill-header "time-helper" "Getting time..."

Why: This pattern helps users identify which skill is executing which command, improving transparency and debugging.

🎨 VISUAL OUTPUT FORMATTING

CRITICAL: All time-helper output MUST use the colored-output formatter skill!

Use Colored-Output Skill

Instead of writing ANSI codes manually, use the centralized formatter:

bash

bash .claude/skills/colored-output/color.sh [type] "time-helper" [message]

Required Output Format

IMPORTANT: Use MINIMAL colored output (2-3 calls max) to prevent screen flickering!

Example formatted output (MINIMAL PATTERN):

bash

# START: Header only
bash .claude/skills/colored-output/color.sh skill-header "time-helper" "Getting current time for Tokyo..."

# MIDDLE: Regular text (no colored calls)
Querying timezone database...
Current time: 2025-10-22 14:30:00 JST
UTC offset: +09:00

# END: Result only
bash .claude/skills/colored-output/color.sh success "" "Time retrieved successfully"

When to Use Colored Output

DO Use:

Initial header: bash .claude/skills/colored-output/color.sh skill-header "time-helper" "Processing..."
Final result: bash .claude/skills/colored-output/color.sh success "" "Complete"
Errors only: bash .claude/skills/colored-output/color.sh error "" "Invalid timezone"

DON'T Use:

❌ Progress updates - use regular text
❌ Info messages - use regular text
❌ Intermediate steps - use regular text

WHY: Each bash call creates a task in Claude CLI, causing screen flickering. Keep it minimal!

Usage Examples

Get Current Time

/time-helper "current time"
/time-helper "what time is it in Tokyo"
/time-helper "time in America/New_York"

Convert Between Timezones

/time-helper "convert 3pm EST to Tokyo"
/time-helper "what's 14:00 UTC in PST"
/time-helper "3:00 PM New York time in London"

Time Calculations

/time-helper "5 hours from now"
/time-helper "30 days from today"
/time-helper "what date is 2 weeks from now"

List Timezones

/time-helper "list timezones America"
/time-helper "find timezone for London"
/time-helper "show all Europe timezones"

DST Information

/time-helper "is EST in daylight saving"
/time-helper "DST status for Europe/Paris"

How It Works

When user asks about time/timezone:

Determine Command Type: Analyze user request (current time, conversion, calculation, list, DST)
Extract Parameters: Timezone names, times, offsets
Execute PHP Script: Run cross-platform time-helper.php
Return Formatted Output: Human-readable response

Commands for PHP Script

The skill uses ~/.claude/skills/time-helper/time-helper.php script:

Get Current Time

bash

php ~/.claude/skills/time-helper/time-helper.php now "Asia/Tokyo"
php ~/.claude/skills/time-helper/time-helper.php now "America/New_York"
php ~/.claude/skills/time-helper/time-helper.php now "Europe/London"

Convert Time Between Timezones

bash

php ~/.claude/skills/time-helper/time-helper.php convert "15:00" "America/New_York" "Asia/Tokyo"
php ~/.claude/skills/time-helper/time-helper.php convert "2025-10-20 14:00" "UTC" "America/Los_Angeles"

Add Time Offset

bash

php ~/.claude/skills/time-helper/time-helper.php add "5 hours"
php ~/.claude/skills/time-helper/time-helper.php add "30 days"
php ~/.claude/skills/time-helper/time-helper.php add "2 weeks" "2025-10-20"

Subtract Time Offset

bash

php ~/.claude/skills/time-helper/time-helper.php subtract "3 hours"
php ~/.claude/skills/time-helper/time-helper.php subtract "7 days"

List Available Timezones

bash

php ~/.claude/skills/time-helper/time-helper.php list
php ~/.claude/skills/time-helper/time-helper.php list "America"
php ~/.claude/skills/time-helper/time-helper.php list "Europe"
php ~/.claude/skills/time-helper/time-helper.php list "Asia"

Check DST Status

bash

php ~/.claude/skills/time-helper/time-helper.php dst "America/New_York"
php ~/.claude/skills/time-helper/time-helper.php dst "Europe/Paris"

Example Interactions

Example 1: Current Time Query

User: "What time is it in Tokyo?"

Execute:

bash

php ~/.claude/skills/time-helper/time-helper.php now "Asia/Tokyo"

Output:

🕐 Sunday, October 20, 2025 - 8:03:51 PM JST
   Timezone: Asia/Tokyo
   UTC Offset: +09:00

Example 2: Timezone Conversion

User: "Convert 3pm EST to Tokyo time"

Execute:

bash

php ~/.claude/skills/time-helper/time-helper.php convert "15:00" "America/New_York" "Asia/Tokyo"

Output:

📍 Original:  3:00 PM EST (Sunday, Oct 20, 2025)
📍 Converted: 4:00 AM JST (Monday, Oct 21, 2025)

From: America/New_York
To:   Asia/Tokyo

Example 3: Time Calculation

User: "What's the date 30 days from now?"

Execute:

bash

php ~/.claude/skills/time-helper/time-helper.php add "30 days"

Output:

📅 Base time:   2025-10-20 11:03:51 UTC
➕ Adding:      30 days
📅 Result:      2025-11-19 11:03:51 UTC

   (Tuesday, November 19, 2025 at 11:03 AM)

Example 4: List Timezones

User: "Show me all America timezones"

Execute:

bash

php ~/.claude/skills/time-helper/time-helper.php list "America"

Output:

🌍 Available Timezones (filtered by 'America'):
═══════════════════════════════════════
   • America/New_York
   • America/Los_Angeles
   • America/Chicago
   • America/Denver
   ... (142 more)

Total: 146 timezone(s)

Example 5: DST Check

User: "Is New York in daylight saving time?"

Execute:

bash

php ~/.claude/skills/time-helper/time-helper.php dst "America/New_York"

Output:

🌞 Timezone: America/New_York
   Current time: 2025-10-20 07:03:51 EDT
   DST Active: ✅ Yes
   UTC Offset: -04:00
   Abbreviation: EDT

Common Timezone Names

United States

America/New_York - Eastern Time (ET)
America/Chicago - Central Time (CT)
America/Denver - Mountain Time (MT)
America/Los_Angeles - Pacific Time (PT)
America/Anchorage - Alaska Time (AKT)
Pacific/Honolulu - Hawaii Time (HST)

Europe

Europe/London - UK (GMT/BST)
Europe/Paris - France (CET/CEST)
Europe/Berlin - Germany (CET/CEST)
Europe/Rome - Italy (CET/CEST)
Europe/Madrid - Spain (CET/CEST)
Europe/Moscow - Russia (MSK)

Asia

Asia/Tokyo - Japan (JST)
Asia/Shanghai - China (CST)
Asia/Hong_Kong - Hong Kong (HKT)
Asia/Singapore - Singapore (SGT)
Asia/Dubai - UAE (GST)
Asia/Kolkata - India (IST)

Others

UTC - Coordinated Universal Time
Australia/Sydney - Australia East (AEST/AEDT)
Pacific/Auckland - New Zealand (NZST/NZDT)

Natural Language Processing

When User Says... Execute This:

User Request	Command
"What time is it in [city/timezone]?"	`php ... now "[timezone]"`
"Current time [timezone]"	`php ... now "[timezone]"`
"Convert [time] [from] to [to]"	`php ... convert "[time]" "[from_tz]" "[to_tz]"`
"[time] [from_tz] in [to_tz]"	`php ... convert "[time]" "[from_tz]" "[to_tz]"`
"[X] hours/days from now"	`php ... add "[X] hours/days"`
"[X] hours/days ago"	`php ... subtract "[X] hours/days"`
"List timezones [filter]"	`php ... list "[filter]"`
"Is [tz] in daylight saving?"	`php ... dst "[timezone]"`

Timezone Abbreviation Mapping

Map common abbreviations to full timezone identifiers:

Abbrev	Full Timezone
EST/EDT	America/New_York
CST/CDT	America/Chicago
MST/MDT	America/Denver
PST/PDT	America/Los_Angeles
GMT/BST	Europe/London
CET/CEST	Europe/Paris
JST	Asia/Tokyo
CST (China)	Asia/Shanghai
IST	Asia/Kolkata
AEST/AEDT	Australia/Sydney

Technical Details

Features

✅ 594+ timezone identifiers supported
✅ Automatic DST handling
✅ Cross-platform (Windows/Mac/Linux)
✅ No external dependencies (native PHP)
✅ DateTimeImmutable for thread safety
✅ Error handling with helpful messages

Requirements

PHP 7.4+ (SubsHero uses PHP 8.3+)
DateTimeZone class (included in PHP core)

Token Efficiency

Without this skill: Use MCP (~400 tokens/query)
With this skill: Direct PHP execution (~130 tokens/query)
10 time queries: Save 2,700 tokens per session!

Error Handling

Invalid Timezone

Input: php ... now "Invalid/Timezone"

Output:

❌ Error: Invalid timezone 'Invalid/Timezone'
   Use 'list' command to see available timezones

Invalid Time Format

Input: php ... convert "invalid" "UTC" "EST"

Output:

❌ Error: Failed to parse time string 'invalid'

Missing Arguments

Input: php ... now

Output:

❌ Error: Missing timezone argument
Usage: php time-helper.php now <timezone>

Maintenance

Adding New Features

To add new commands, edit time-helper.php:

Add new function (e.g., function getBusinessHours())
Add case to switch statement
Update skill.md with usage examples

Testing

Test all commands directly:

bash

cd ~/.claude/skills/time-helper
php time-helper.php now "UTC"
php time-helper.php convert "12:00" "UTC" "America/New_York"
php time-helper.php add "5 hours"
php time-helper.php list "America"
php time-helper.php dst "Europe/London"

Migration from Timezone MCP

If you previously used a timezone MCP server:

✅ Install this skill (2 files created)
🧪 Test all use cases (verify same functionality)
🗑️ Remove Timezone MCP from .mcp.json
💾 Enjoy 67% token savings on all time queries!

Support

File Location: ~/.claude/skills/time-helper/

Files:

skill.md - This documentation
time-helper.php - Cross-platform PHP script

Timezone List: Use php time-helper.php list to see all 594 timezones

Common Issues:

If PHP not found: Ensure PHP is in PATH
If timezone invalid: Use list command to find correct name
If DST info unavailable: Some timezones don't observe DST

Version History

v1.0.0 (2025-10-20)

Initial release
Get current time in any timezone
Convert between timezones
Time calculations (add/subtract)
List available timezones with filtering
DST detection and status
Cross-platform PHP script (Windows/Mac/Linux)
67% token savings vs. MCP servers

Search AI Tools

Install this agent skill to your Project

SKILL.md

Time & Timezone Helper Skill

Overview

🔧 BASH COMMAND ATTRIBUTION PATTERN

🎨 VISUAL OUTPUT FORMATTING

Use Colored-Output Skill

Required Output Format

When to Use Colored Output

Usage Examples

Get Current Time

Convert Between Timezones

Time Calculations

List Timezones

DST Information

How It Works

Commands for PHP Script

Get Current Time

Convert Time Between Timezones

Add Time Offset

Subtract Time Offset

List Available Timezones

Check DST Status

Example Interactions

Example 1: Current Time Query

Example 2: Timezone Conversion

Example 3: Time Calculation

Example 4: List Timezones

Example 5: DST Check

Common Timezone Names

United States

Europe

Asia

Others

Natural Language Processing

When User Says... Execute This:

Timezone Abbreviation Mapping

Technical Details

Features

Requirements

Token Efficiency

Error Handling

Invalid Timezone

Invalid Time Format

Missing Arguments

Maintenance

Adding New Features

Testing

Migration from Timezone MCP

Support

Version History

v1.0.0 (2025-10-20)