utc-zoned-temporal-types
UTC Zoned Temporal Types
Goal
When the stack supports timezone-aware built-in or standard-library temporal types, use those types and set their timezone to UTC.
Treat this skill as normalization guidance for timezone-aware temporal values. The key question is whether the code can use a built-in temporal type that carries timezone semantics. If it can, represent the value in UTC instead of server-local time, user-local time, or an arbitrary geographic timezone.
What Counts as In Scope
Apply this skill to code that does one or more of these things:
- defines timezone-aware datetime or timestamp fields
- defines temporal parameters or return types that can carry timezone information
- parses or serializes timezone-aware temporal values
- maps timezone-aware values to persistence or transport boundaries
- converts between local time and a normalized stored or exchanged value
- configures default timezones for timezone-aware temporal types
UTC Rule
-
Use timezone-aware built-in temporal types when the stack provides them.
- Prefer the native or standard-library temporal type that can carry timezone semantics.
- Do not fall back to naive local datetimes when a timezone-aware built-in type is available.
-
Use UTC as the timezone.
- Use the canonical UTC representation provided by the language or standard library.
- Prefer named UTC constructs such as
UTC,Z, or the standard-library UTC zone object over ad hoc local timezone settings.
-
Normalize at boundaries.
- Convert external or local values to UTC as they enter the system when the task requires a timezone-aware built-in type.
- Serialize or persist the normalized UTC value unless the boundary contract explicitly requires another representation.
-
Keep UTC semantics explicit.
- Make it obvious in types, constructors, helpers, and serialization code that the value is timezone-aware and normalized to UTC.
- Do not rely on server defaults, process defaults, database session defaults, or ambient local timezone configuration.
Detection Workflow
-
Determine whether the value can be timezone-aware.
- Identify whether the field, parameter, or contract represents a datetime or timestamp that the stack can model with a timezone-aware built-in type.
- Ignore date-only and time-only values that do not carry timezone semantics.
-
Detect built-in timezone-aware support in the stack.
- Identify the native or standard-library temporal types that support timezone-aware values.
- Follow the project's established conventions for constructing, storing, and serializing those types.
-
Trace normalization points.
- Identify where values enter the system from user input, APIs, databases, jobs, or integrations.
- Identify where local or offset-based inputs must be converted into UTC.
- Verify that later reads, writes, and comparisons keep the value in UTC.
Writing or Changing Temporal Code
-
Prefer timezone-aware built-in types over naive ones.
- Use the built-in timezone-aware temporal type when the stack supports it.
- Avoid storing the same concept as a naive local datetime plus an implicit timezone assumption.
-
Set or construct values in UTC.
- Use the standard UTC zone, UTC clock, or UTC constructor path provided by the stack.
- Avoid local-now helpers or system-default timezone constructors when a UTC alternative exists.
-
Convert only at the edges when needed.
- Convert from user-facing or boundary-specific representations into UTC near the boundary.
- Keep the internal timezone-aware representation in UTC once normalized.
-
Keep serialization and persistence aligned.
- Persist or emit timezone-aware values in a UTC-safe format.
- Preserve the fact that the stored or exchanged value is UTC.
Review Questions
When reading or reviewing code, ask:
- Can this value be represented with a built-in timezone-aware temporal type?
- If so, is the code using that type instead of a naive local datetime?
- Is the timezone explicitly UTC?
- Is the code relying on server-local or process-default timezone behavior instead of UTC?
- Would changing this code risk losing UTC normalization for timezone-aware values?
If the answer is yes, apply this skill.
Report the Outcome
When finishing the task:
- state which timezone-aware temporal values or types were identified or changed
- state which built-in or standard-library timezone-aware types were used
- state where UTC construction, normalization, serialization, or persistence was implemented or preserved
More from code-sherpas/agent-skills
neverthrow-return-types
Require `neverthrow`-based return types in TypeScript and JavaScript code whenever the surrounding technology allows it. Use when creating, refactoring, reviewing, or extending standalone functions, exported module functions, class methods, object methods, service methods, repository methods, and similar APIs that should expose explicit success and failure result types in their signatures. Prefer `Result<T, E>` for synchronous code and `ResultAsync<T, E>` for asynchronous code. Only skip a `neverthrow` return type when a framework, library, runtime interface, or externally imposed contract is incompatible and requires a different return shape.
16neverthrow-wrap-exceptions
Capture exceptions and promise failures with `neverthrow` instead of hand-written `try/catch` in TypeScript and JavaScript code. Use when wrapping synchronous functions that may throw, promise-returning functions that may throw before returning, existing `PromiseLike` values that may reject, or third-party APIs such as parsers, database clients, HTTP clients, file-system helpers, serializers, and SDK calls. Prefer `Result.fromThrowable` for synchronous throwers, `ResultAsync.fromThrowable` for promise-returning functions that may throw or reject, and `ResultAsync.fromPromise` when you already have a `PromiseLike` value in hand. Only keep `try/catch` when the language construct, cleanup requirement, or framework boundary truly requires it.
11atomic-design
Create or update web UI components with a strict reuse-first workflow. Use when building, refactoring, restyling, or extending frontend or template components while minimizing raw DOM or HTML by reusing or generalizing existing components first.
10write-persistence-representations
Create or update persistence-layer data representations in any stack, including ORM entities, schema definitions, table mappings, document models, collection definitions, and similar database-facing code. Use when agents needs to add or change persisted fields, identifiers, relationships, indexes, timestamps, auditing fields, or storage mappings in frameworks, libraries, or ORMs such as Prisma, TypeORM, Sequelize, Drizzle, Mongoose, Hibernate/JPA, Doctrine, Ecto, Active Record, or equivalent persistence technologies.
7business-logic
Identify, interpret, review, or write business logic in code. Use when an agent needs to decide whether code expresses business rules, business algorithms, or business workflows, or when it must implement, preserve, or refactor code that creates, stores, or transforms data according to real business policies.
7immutable-domain-entities
Require the immutable design pattern for domain entities. Use when an agent needs to create, modify, review, or interpret domain entities and should preserve identity while expressing state changes through new immutable instances. Domain entities must be modeled as immutable classes, not as plain type aliases or interfaces paired with standalone functions.
7