---
name: time-conversion
description: |
  Deterministically convert between datetime strings and Unix timestamps (seconds/milliseconds/nanoseconds),
  including timezone offsets (e.g., "+0800") and UTC normalization.
  Use when the user asks to convert time strings to timestamps, timestamps to ISO 8601, calculate time windows
  (e.g., "±30m", "last 2h"), or when any tool call requires `from`/`to` times and you must avoid hallucinating.
  Trigger phrases: "timestamp", "epoch", "Unix time", "time range", "from/to", "timezone", "UTC", "时间戳", "毫秒", "纳秒".
---

# Time Conversion

Convert time strings to timestamps without hallucination by always executing the bundled script.

## Non-negotiable rules

- **Never convert in your head.** Always run `scripts/time_convert.py`.
- Always state:
  - The input timezone (from the string or `--assume-tz`)
  - The output timezone (usually UTC)
  - The unit (`s`, `ms`, `ns`)
- If a datetime string has **no timezone**, require `--assume-tz <IANA|UTC|+08:00>` (do not guess).

## Quick start

```bash
cd .opencode/skills/builtin/time-conversion

# Parse issue_meta.json `created` (e.g., "2026-03-09T12:33:54.230+0800") to epoch ms
python3 scripts/time_convert.py dt-to-ts --dt '2026-03-09T12:33:54.230+0800' --field epoch_ms

# Convert Grafana epoch ms -> UTC ISO 8601
python3 scripts/time_convert.py ts-to-dt --ts 1773166172000 --unit ms --tz UTC --field utc_iso

# Build a +/- 30m window around a center time
python3 scripts/time_convert.py window --center-dt '2026-03-09T12:33:54.230+0800' --before 30m --after 30m --field start.epoch_ms
python3 scripts/time_convert.py window --center-dt '2026-03-09T12:33:54.230+0800' --before 30m --after 30m --field end.epoch_ms
```

## Common use cases

### Read issue_meta.json and convert safely

1. Read `issues/<issue_id>/issue_meta.json`
2. Extract `created` (it includes a timezone offset like `+0800`)
3. Convert via script; treat script output as the source of truth

### Tool unit cheatsheet

| Destination | Typical unit | Notes |
|-------------|--------------|------|
| Grafana `from`/`to` URL params | `ms` | Milliseconds since epoch |
| Loki API | `ns` or RFC3339 | Many endpoints accept nanoseconds since epoch |
| Metric API queries | ISO 8601 | Prefer UTC (`...Z`) |

## Script reference

Run `python3 scripts/time_convert.py --help` for full CLI help.

Output is JSON by default. Use `--field <key>` to print a single value (supports dot paths like `start.epoch_ms`).