timezone handling

    1

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

    Free

    1 useSecurity scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 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.

    Focuses on wall-clock time and calendar scheduling. Not for measuring high-precision elapsed time or durations requiring a monotonic clock.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 28 days ago

    • Free with an Agensi account

    Permissions

    No special permissions declared or detected

    Listed28 days ago

    What's inside

    Frequently Asked Questions

    This skill fixes common production issues like off-by-one-hour errors caused by Daylight Saving Time and data corruption stemming from storing timestamps without specific offset information.

    The skill is stack-agnostic and works with any AI agent capable of code generation or system architecture design, with specific optimizations for PostgreSQL, Python, Node.js, and Docker environments.

    You will receive a specialized protocol for auditing existing code, a set of robust schema design patterns, and logic modules for handling edge cases like DST transitions and IANA zone naming.

    Unlike generic prompts that may recommend deprecated methods like `utcnow()`, this skill enforces a strict 'UTC-at-rest' architecture and IANA-compliant naming to ensure your system remains accurate during global clock shifts.

    Setup involves integrating the skill's temporal logic into your agent's workflow, which then guides the auditing of your database schema, application code, and server environment variables.

    This skill focuses on human-readable wall-clock time and calendar scheduling; it is not designed for high-precision latency measurements or sub-millisecond durations where monotonic clocks are required.

    New in APIs & Backend