dates

name	dates
description	Use this skill when: Format dates, handle timezones, parse date strings, calculate date differences, or do any date/time arithmetic. Focus on user intent. Trigger keywords: date-formatting, date-time, timezone, date-fns.

Date & Time

Always use date-fns (and date-fns-tz for timezones). Never use Moment.js, Day.js, or native display methods.

Format tokens

Token	Output
PPP	March 24, 2026
PPpp	March 24, 2026 at 3:45 PM
yyyy-MM-dd	2026-03-24
HH:mm / h:mm a	15:45 / 3:45 PM
E, MMM d	Mon, Mar 24

Common patterns

import { format, parseISO, parse, addDays, subDays, addMonths,
         startOfDay, endOfDay, isAfter, isBefore,
         differenceInDays, formatDistanceToNow } from 'date-fns';
import { formatInTimeZone, toZonedTime } from 'date-fns-tz';

// Format
format(new Date(), 'PPP');                        // "March 24, 2026"
format(parseISO('2026-03-24T15:45:00Z'), 'PPpp'); // from ISO string

// Parse custom string
parse('24/03/2026', 'dd/MM/yyyy', new Date());

// Arithmetic (immutable — always returns new Date)
addDays(new Date(), 1);   subDays(new Date(), 1);
addMonths(new Date(), 1); startOfDay(new Date()); endOfDay(new Date());

// Compare
isAfter(a, b);  isBefore(a, b);  differenceInDays(end, start);

// Relative
formatDistanceToNow(date, { addSuffix: true }); // "4 days ago"

// Timezone
formatInTimeZone(new Date(), 'America/New_York', 'PPpp');
format(toZonedTime(new Date(), 'Europe/Berlin'), 'HH:mm zzz');

Gotchas

• parseISO() for strings from API/DB — never new Date(string).
• Prisma returns real Date objects — pass directly to format().
• format() uses local timezone by default; use formatInTimeZone() for explicit TZ.
• Store raw Date/ISO in state; format only at render time.