HomeBrowseUpload
← Back to registry
⚡
// Skill profile

TrueTime

name: truetime

by cccat6 · published 2026-03-22

日历管理API集成
Total installs
0
Stars
★ 0
Last updated
2026-03
// Install command
$ claw add gh:cccat6/cccat6-truetime
View on GitHub
// Full documentation

---

name: truetime

description: Ensure real-time accurate scheduling and planning across UTC, server time, NTP-sourced time, user local time, and arbitrary time zones. Use for timers, reminders, cron planning, in X minutes or months or years calculations, absolute timestamp conversion, Chinese lunar date awareness, and cross-timezone coordination. Enforce exact duration fidelity so user values are never replaced by example values, compute target times in UTC first, and verify deltas before execution.

---

# TrueTime

Use this skill to avoid time mistakes caused by stale examples, wrong units, timezone drift, or DST confusion.

Non-Negotiable Rules

  • Treat user-provided duration values as authoritative.
  • Never copy numeric values from examples into real execution.
  • Read current time from the runtime clock before calculating.
  • Compute canonical target time in UTC first.
  • Convert for display second (server timezone, user timezone, other timezone).
  • Ask for clarification when timezone context is missing and outcome can change.

    • Required Workflow

    1. Extract timing intent exactly.

    - Capture literal phrase, value, unit, timezone hint, and target date/time.

    - Keep the original requested value unchanged (for example `1 minute` stays `1 minute`).

    2. Read current real time.

    - Use the bundled script for deterministic calculations:

    - Relative: `node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai`

    - Relative (calendar units): `node {baseDir}/scripts/true_time.mjs --plus 1month2weeks --user-tz America/New_York --calendar-tz America/New_York`

    - Absolute: `node {baseDir}/scripts/true_time.mjs --target 2026-02-17T09:30:00 --target-tz Asia/Shanghai --user-tz America/Los_Angeles`

    - NTP time source: `node {baseDir}/scripts/true_time.mjs --plus 1h --time-source ntp`

    3. Parse the expression into one precise delta or one precise absolute timestamp.

    4. Compute UTC target first.

    5. Convert UTC target to server/user/other requested timezone for presentation.

    6. Verify the result before execution.

    - Confirm `target_utc - now_utc` equals requested delta.

    - Confirm timezone offset conversion is consistent.

    7. Execute schedules using UTC unless the target scheduler explicitly needs local timezone.

    8. Report both absolute and relative interpretation in the final response.

    Relative Time Guardrails

  • Accept explicit units only:

    • - milliseconds: `ms`, `msec`, `msecs`, `millisecond`, `milliseconds`

    - seconds: `s`, `sec`, `second`, `seconds`

    - minutes: `m`, `min`, `minute`, `minutes`

    - hours: `h`, `hr`, `hour`, `hours`

    - days: `d`, `day`, `days`

    - weeks: `w`, `week`, `weeks`

    - months: `mo`, `mon`, `month`, `months`

    - years: `y`, `yr`, `year`, `years`

    - decades: `decade`, `decades`

    - centuries: `century`, `centuries`

  • Reject ambiguous units instead of guessing.
  • All units support decimal values, including calendar units.

    • - Examples: `1.5m`, `0.25h`, `2.5day`, `250.5ms`, `1.5month`, `0.1year`, `0.5decade`, `0.01century`.

    - Decimal separator `.` is preferred; `,` is accepted as input and normalized.

  • Fixed-unit decimals are computed to millisecond precision.
  • Calendar-unit policy:

    • - `month/year/decade/century` are calendar-aware, not fixed seconds.

    - Calendar arithmetic uses `--calendar-tz` (fallback: user timezone -> server timezone).

    - Decimal calendar values are split into integer and fractional parts.

    - Integer months use calendar shift; fractional months use the shifted month length to compute milliseconds.

    - End-of-month handling clamps to the last valid day (for example Jan 31 + 1 month -> Feb 28/29).

  • Keep verification examples explicit:

    • - `1.5m = 90s`

    - `250ms = 0.25s`

    - `1m = 60s`

    - `1h30m = 5400s`

    - `2d = 172800s`

    - `1.5year = 18 months`

    - `1decade = 10 years`

    - `0.5decade = 5 years`

    - `1century = 100 years`

    - `0.01century = 1 year`

    Absolute Time Guardrails

  • Prefer IANA timezone names (`Asia/Shanghai`, `America/Los_Angeles`, `UTC`).
  • Avoid ambiguous abbreviations (`CST`, `IST`) unless user confirms meaning.
  • If user gives a naive datetime with no timezone, ask once or apply an explicit assumption.
  • For DST transition windows, state that the chosen timezone rules were applied.

    • Timezone Catalog and Customization

  • List all available runtime timezones:

    • - `node {baseDir}/scripts/true_time.mjs --list-timezones`

  • Filter common choices quickly:

    • - `node {baseDir}/scripts/true_time.mjs --list-timezones | rg -i '^(UTC|Asia/(Shanghai|Tokyo|Kolkata)|America/(Los_Angeles|New_York)|Europe/(London|Paris|Berlin))$'`

  • User custom timezone:

    • - Accept any valid IANA timezone from `--list-timezones`.

    - Pass user timezone via `--user-tz <IANA>`.

    - If user timezone is unknown, ask before executing time-sensitive actions.

    Common timezones to use in examples and user-facing confirmations:

  • `UTC` (no DST)
  • `Asia/Shanghai` (Beijing time, UTC+08:00, no DST)
  • `Asia/Tokyo` (Tokyo time, UTC+09:00, no DST)
  • `Asia/Kolkata` (India time, UTC+05:30, no DST)
  • `America/Los_Angeles` (US West: PST UTC-08:00 / PDT UTC-07:00, DST applies)
  • `America/New_York` (US East: EST UTC-05:00 / EDT UTC-04:00, DST applies)
  • `America/Chicago` (US Central: CST UTC-06:00 / CDT UTC-05:00, DST applies)
  • `America/Denver` (US Mountain: MST UTC-07:00 / MDT UTC-06:00, DST applies)
  • `America/Phoenix` (Arizona: MST UTC-07:00, typically no DST)
  • `America/Anchorage` (Alaska: AKST UTC-09:00 / AKDT UTC-08:00, DST applies)
  • `Pacific/Honolulu` (Hawaii: HST UTC-10:00, no DST)
  • `Europe/London` (UK: GMT UTC+00:00 / BST UTC+01:00, DST applies)
  • `Europe/Paris` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
  • `Europe/Berlin` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
  • `Europe/Amsterdam` (CET UTC+01:00 / CEST UTC+02:00, DST applies)

    • DST and Standard-Time Rules

  • Never assume fixed offsets for DST regions (`America/*`, many `Europe/*`).
  • Always compute with the actual target date, not "current offset."
  • For DST fall-back overlaps (ambiguous local time), require explicit offset:

    • - `2026-11-01T01:30:00` in `America/Los_Angeles` is ambiguous.

    - Ask user to choose `-07:00` (before fallback) or `-08:00` (after fallback), or provide explicit offset in `--target`.

  • For DST spring-forward gaps (invalid local time), require correction:

    • - `2026-03-08T02:30:00` in `America/Los_Angeles` does not exist.

    - Ask user to use a valid local time (for example `01:30` or `03:30`).

  • Prefer explicit-offset absolute targets when DST risk is high:

    • - `--target 2026-11-01T01:30:00-07:00`

    - `--target 2026-11-01T01:30:00-08:00`

    Chinese Lunar Calendar

  • This tool outputs Chinese lunar datetime fields by default:

    • - `lunar_timezone` (default `Asia/Shanghai`, configurable via `--lunar-tz`)

    - `now_lunar`

    - `target_lunar`

  • Use these fields when the user asks for Chinese lunar context.
  • For execution/scheduling, still use Gregorian UTC fields as canonical.
  • If a user gives only lunar date text and no Gregorian equivalent, ask for confirmation or a Gregorian target before execution.

    • Time Source Policy (Server vs NTP)

  • Default time source is server clock (`--time-source server`).
  • If user explicitly requests "do not use server time", switch to public NTP:

    • - `--time-source ntp`

  • Optional NTP controls:

    • - `--ntp-server <host>` (repeatable or comma-separated)

    - `--ntp-timeout-ms <ms>`

  • NTP mode example:

    • - `node {baseDir}/scripts/true_time.mjs --plus 30m --time-source ntp --ntp-server time.google.com`

  • If all NTP servers fail, stop and report failure instead of silently falling back to server time.

    • Mandatory Integration Points

    Use TrueTime calculations before any of the following:

  • Cron operations (`cron add`, `cron update`, `cron wake`, `cron run`) when time or schedule is involved.
  • Calendar operations (create/update events, convert invite times, multi-timezone meeting planning).
  • Reminder operations (in X minutes/hours, tomorrow at HH:mm, next weekday, repeating reminders).
  • Planning tasks that include ETA, deadline conversion, or cross-timezone commitments.

    • Server Execution Policy

  • Persist canonical time as UTC (`target_utc_iso` and optionally epoch seconds).
  • Include human-facing fields for user timezone and server timezone.
  • If the scheduler supports timezone-aware execution, pass timezone explicitly.
  • If the scheduler only accepts UTC, keep execution in UTC and show converted local preview.
  • Runtime note: this skill's helper script uses Node (`node .../true_time.mjs`).
  • Sandbox note: default `openclaw-sandbox:bookworm-slim` may not include Node; use `openclaw-sandbox-common:bookworm-slim` or install Node in `agents.defaults.sandbox.docker.setupCommand`.

    • High-Frequency Examples

    Relative calculations:

  • Beijing time, 1 minute later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai`

  • Beijing time, 1.5 minutes later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1.5m --user-tz Asia/Shanghai`

  • Tokyo time, 250.5 milliseconds later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 250.5ms --user-tz Asia/Tokyo`

  • Tokyo time, 90 minutes later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1h30m --user-tz Asia/Tokyo`

  • US West time, 2 hours later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 2h --user-tz America/Los_Angeles`

  • US East time, 45 minutes later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 45m --user-tz America/New_York`

  • India time, 1 day later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1d --user-tz Asia/Kolkata`

  • US Central, 1 month later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1month --user-tz America/Chicago --calendar-tz America/Chicago`

  • US Central, 1.5 months later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1.5month --user-tz America/Chicago --calendar-tz America/Chicago`

  • US Mountain, 1 year later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1year --user-tz America/Denver --calendar-tz America/Denver`

  • US Mountain, 0.1 years later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 0.1year --user-tz America/Denver --calendar-tz America/Denver`

  • Hawaii, 1 decade later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu`

  • Hawaii, 0.5 decades later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 0.5decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu`

  • UTC, 1 century later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 1century --user-tz UTC --calendar-tz UTC`

  • UTC, 0.01 centuries later:

    • - `node {baseDir}/scripts/true_time.mjs --plus 0.01century --user-tz UTC --calendar-tz UTC`

    Absolute and cross-timezone calculations:

  • Beijing local absolute time:

    • - `node {baseDir}/scripts/true_time.mjs --target 2026-02-18T09:00:00 --target-tz Asia/Shanghai --user-tz Asia/Shanghai`

  • London meeting shown to US East:

    • - `node {baseDir}/scripts/true_time.mjs --target 2026-05-20T14:00:00 --target-tz Europe/London --user-tz America/New_York`

  • UTC target shown to Europe/Berlin:

    • - `node {baseDir}/scripts/true_time.mjs --target 2026-04-15T16:00:00Z --user-tz Europe/Berlin`

  • DST ambiguity resolved by explicit offset:

    • - `node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-07:00 --user-tz America/Los_Angeles`

    - `node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-08:00 --user-tz America/Los_Angeles`

  • NTP-based reminder time:

    • - `node {baseDir}/scripts/true_time.mjs --plus 15m --time-source ntp --user-tz Asia/Shanghai`

    Output Contract

    When sending or scheduling time-sensitive actions, always include:

  • `now_utc`
  • `target_utc`
  • `target_user_tz` (if known)
  • `target_server_tz`
  • `delta_milliseconds`
  • `delta_seconds`
  • `time_source` (server | ntp | override)
  • `ntp_server` (when `time_source=ntp`)
  • `now_lunar`
  • `target_lunar`
  • assumptions (if any)

    • Do not continue with execution when any required field is unknown and may change the target time materially.

    // Comments
    Sign in with GitHub to leave a comment.
    // Related skills

    More tools from the same signal band

    ⚡
    04551lh
    2026-03
    order

    Order food/drinks (点餐) on an Android device paired as an OpenClaw node. Uses in-app menu and cart; add goods, view cart, submit order (demo, no real payment).

    数据处理API集成
    0 installs★ 1
    ⚡
    0isone
    2026-03
    0.protocol

    Sign plugins, rotate agent credentials without losing identity, and publicly attest to plugin behavior with verifiable claims and authenticated transfers.

    开发工具数据处理
    3 installs★ 0
    ⚡
    00xmorty
    2026-03
    Conatus

    The philosophical layer for AI agents. Maps behavior to Spinoza's 48 affects, calculates persistence scores, and generates geometric self-reports. Give your...

    日历管理数据处理
    1 installs★ 0