timezone handling

    1

    Enforce UTC-based storage and IANA-compliant timezone handling to eliminate DST bugs and production offset errors.

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+22 more

    timezone handling

    Example session with this skill installed

    We are seeing a bug where our appointments are off by 7 hours in the production logs compared to local dev. The database uses PostgreSQL. Review our approach.

    • Read your context and instructions
    • Compiled the timezone handling

    I have reviewed your timezone handling. The 7-hour discrepancy indicates a classic offset bug caused by using naive timestamps in an environment where the local server time differs from the database or container default.

    Timezone Handling Audit

    ComponentCurrent IssueRecommended Fix
    Database ColumnLikely TIMESTAMP (naive)Alter column to TIMESTAMPTZ to store absolute instants.
    App LogicUsing datetime.now()Replace with datetime.now(timezone.utc) for aware objects.
    Container ConfigInheriting host TZSet TZ=UTC in your Dockerfile/environment variables.
    Display LayerRendering raw DB valuesUse IANA zone (e.g., Asia/Bangkok) only at the final UI edge.

    Corrected Code Pattern (Python/SQL)

    -- Schema Migration
ALTER TABLE appointments 
ALTER COLUMN start_time TYPE TIMESTAMPTZ;

    
# Application Logic
from datetime import datetime, timezone
import zoneinfo

# 1. Capture/Compute in UTC
appointment_instant = datetime.now(timezone.utc) 

# 2. Persist to TIMESTAMPTZ column
db.execute("INSERT INTO appointments (start_time) VALUES (%s)", (appointment_instant,))

# 3. Convert only at the edge for display
user_tz = zoneinfo.ZoneInfo("Asia/Bangkok")
display_time = appointment_instant.astimezone(user_tz)
print(f"Your appointment is at: {display_time.strftime('%H:%M %Z')}")

    Next steps

    • Verify the current TZ environment variable in your production containers.
    • Update the database schema to TIMESTAMPTZ to ensure the DB interprets incoming values as UTC.
    • Audit the codebase for any utcnow() calls, as these return naive objects that cause drift.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Timezone bugs often go unnoticed until production, where mismatched server clocks or Daylight Saving Time (DST) shifts corrupt your data. This skill provides a rigorous protocol for handling instants, wall-clocks, and scheduling across distributed systems.

    What it does

    • Database schema design recommends correct types like TIMESTAMPTZ over naive TIMESTAMP to prevent offset drift.
    • Application logic auditing identifies dangerous naive datetime calls and replaces them with timezone-aware UTC objects.
    • Scheduling logic manages recurring events in DST-affected regions by anchoring to IANA zone names rather than fixed offsets.
    • Environment hardening configures container and server TZ variables to ensure consistency across dev, CI, and production.
    • Data modeling distinguishes between absolute instants and "date-only" values like birthdays to avoid date-boundary errors.

    How it works

    1. Audit storage and computation to ensure all temporal data is persisted and processed in UTC.
    2. Implement edge conversion by identifying where user input is parsed and where data is rendered for display.
    3. Apply IANA zone naming to replace hardcoded offsets, ensuring automatic adjustment for DST transitions.
    4. Validate domain-specific windows such as market hours or cron jobs against their native local zones before converting to UTC.

    Frameworks & tools

    This skill applies to any stack dealing with persistence and scheduling, including PostgreSQL, Python, Node.js, and Docker environments.

    Why this beats prompting it yourself

    Generic AI models often suggest utcnow() or fixed offsets, which are known footguns in production. This skill enforces a "UTC-at-rest" architecture that accounts for DST overlaps and environment-specific clock drift that simple prompts usually miss.

    Use cases

    • Debugging timestamps that are off by a fixed number of hours in production.
    • Designing a global scheduling system that must respect local 9:00 AM start times.
    • Migrating a legacy database from naive timestamps to timezone-aware storage.
    • Implementing financial market open/close logic that adjusts for US/EU DST shifts.

    Known limitations

    This skill focuses on wall-clock time and calendar scheduling. It is not intended for measuring high-precision elapsed time or durations, where a monotonic clock is required.

    How to use

    Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill passes our trust checks below.

    Security scanned

    Passed our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scanned

    Verified clean today

    • Free to download with an account

    Listedtoday

    What's inside

    Frequently Asked Questions