Timezone Enforcement Skill

Enforces correct local-time awareness for this agent. Prevents the classic UTC-as-local mistake.

What This Skill Does

When installed, this skill:

1. Reads the user timezone from USER.md (Timezone: field)
2. Ensures timezone is applied when the agent calls now.py for time output
3. Provides /timezone command for users to check/set timezone
4. Validates that the agent never reports UTC time as local time
5. Patches AGENTS.md with standing timezone instructions

Prerequisites — Required Before Install

USER.md must contain a timezone field in this exact format: Timezone: America/New_York

Use a valid IANA timezone string. Examples:

• America/New_York
• America/Chicago
• America/Los_Angeles
• Europe/London
• Asia/Tokyo

Do NOT use abbreviations like EST, PST, or free-text like "New York time" — these will fail.

If USER.md does not exist or has no Timezone field, timezone_setup.py will prompt the user to enter one interactively.

Invalid timezone recovery:

• If the string fails IANA validation, halt and show: "Invalid timezone: [input]. Please provide a valid IANA string e.g. America/New_York"
• Do not default silently to UTC
• Do not proceed until a valid string is confirmed

Startup - Run Once on Install

On first use, run: python3 /opt/openclaw/workspace/skills/timezone/scripts/timezone_setup.py

Note: timezone_setup.py requires an interactive shell. For headless or automated environments, pre-populate tz_config.json directly with the IANA string before first run.

This script detects timezone from USER.md, writes TZ_CONFIG to tz_config.json, and patches AGENTS.md. Do not patch AGENTS.md manually until this script has run. It requires a valid tz_config.json first.

Answering What Time Is It

Always run: python3 /opt/openclaw/workspace/skills/timezone/scripts/now.py

Report the output verbatim. Never guess time from internal knowledge. If now.py fails: report the error, ask user to run timezone_setup.py first. Do not guess. If USER.md has no Timezone field: run timezone_setup.py before proceeding. Do not default to UTC silently.

Heartbeat Integration

On every heartbeat where time is mentioned:

1. Call now.py to get current local time
2. If any prior message contains a UTC time presented as local time, flag it
3. If drift over 30 minutes between what agent said and actual time, self-correct If now.py fails during heartbeat: log the failure, skip time reporting, flag to user at next opportunity.

UTC Trap Detection

If about to output a time, ask: Is this UTC or local?

• UTC ends in Z, +00:00, or +0000 — convert before reporting
• Timestamps with no timezone offset at all are ambiguous — treat as UTC and note the assumption to the user
• Times from APIs, cron, system are usually UTC - always convert
• Times in USER.md or user messages are usually local - use as-is

/timezone Command

When user types /timezone:

1. Show current configured timezone and current local time
2. Offer to change
3. If changing: run timezone_setup.py with their input
4. Confirm the change If tz_config.json does not exist: run timezone_setup.py first.

Standing Rules - patch into AGENTS.md only after timezone_setup.py has run

• NEVER report UTC time as local time
• All time output must be in users local timezone
• When in doubt: run now.py before reporting any time
• API/cron/system timestamps are UTC - always convert before displaying
• If now.py fails: flag to user, do not guess

What This Skill Does NOT Do

• Does NOT automatically intercept all time output — the agent must explicitly call now.py before reporting any time
• Does NOT self-correct without being triggered — heartbeat integration requires the agent framework to call now.py on schedule
• Does NOT validate timezone strings at runtime beyond what the system tz database supports
• Does NOT handle multi-user or multi-timezone environments — one timezone per agent instance
• Does NOT detect if USER.md has changed since install — if timezone changes, re-run timezone_setup.py manually to sync tz_config.json