# Current Date And Time Skill

> Use when files need timestamps, APIs need dates, or user asks for current date/time

- Skill: `saiday/current-date-and-time-skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add saiday/current-date-and-time-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/saiday/current-date-and-time-skill/raw
- Safety review: PASS (external: skill-scanner FAIL, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: saiday (https://skillmd.com/u/saiday)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/saiday/current-date-and-time-skill

---


# Current Date and Time Skill

## Overview

This skill provides the current date and time in 8 essential formats through a single command. It outputs standardized timestamps suitable for various use cases including file naming, API queries, database operations, logging, and user-facing displays.

All outputs follow industry standards (ISO 8601, Unix epoch) and are provided as KEY=VALUE pairs for easy integration into shell scripts, automation workflows, and AI agent operations.

Use this skill whenever you need:
- Current date or time in any standard format
- Timestamps for file naming or backup operations
- Date/time values for API requests or database queries
- Human-readable dates for reports or user interfaces
- File-safe timestamps for logs or automated processes

## Quick Start

Run the script to get all date/time formats at once:

```bash
./scripts/datetime.sh
```

**Example output:**
```
DATE_ISO=2026-01-19
DATETIME_ISO=2026-01-19T14:30:05+08:00
DATETIME_UTC=2026-01-19T06:30:05Z
TIMESTAMP_UNIX=1768918205
DATE_HUMAN=January 19, 2026
DATETIME_FILE=20260119-143005
DATE_COMPACT=20260119
TIMEZONE=+08:00
```

To use the values in your script:

```bash
eval "$(./scripts/datetime.sh)"
echo "Today is $DATE_ISO"
echo "Timestamp: $TIMESTAMP_UNIX"
```

## Available Formats

| Variable | Format | Example | Primary Use Cases |
|----------|--------|---------|-------------------|
| `DATE_ISO` | YYYY-MM-DD | 2026-01-19 | Standard date for databases, APIs, sorting |
| `DATETIME_ISO` | YYYY-MM-DDTHH:MM:SS±HH:MM | 2026-01-19T14:30:05+08:00 | Precise timestamp with timezone for APIs, logs |
| `DATETIME_UTC` | YYYY-MM-DDTHH:MM:SSZ | 2026-01-19T06:30:05Z | UTC format for distributed systems |
| `TIMESTAMP_UNIX` | Seconds since epoch | 1768918205 | API timestamps, time calculations |
| `DATE_HUMAN` | Month DD, YYYY | January 19, 2026 | User-facing displays, reports |
| `DATETIME_FILE` | YYYYMMDD-HHMMSS | 20260119-143005 | Filenames, backup files, no special chars |
| `DATE_COMPACT` | YYYYMMDD | 20260119 | Short filenames, database keys |
| `TIMEZONE` | ±HH:MM | +08:00 | Timezone offset awareness |

All timestamps reflect the system's local timezone unless explicitly noted as UTC.

## Common Use Cases

### 1. Creating Timestamped Files and Backups

Create files with timestamps in their names for easy sorting and identification:

```bash
# Load all date/time variables
eval "$(./scripts/datetime.sh)"

# Create a timestamped backup
cp database.db "backups/database-${DATE_ISO}.db"

# Create a log file with full timestamp
touch "logs/app-${DATETIME_FILE}.log"

# Generate a report with human-readable date
echo "Sales Report for $DATE_HUMAN" > "reports/sales-${DATE_COMPACT}.txt"
```

### 2. API Queries with Date Parameters

Pass properly formatted dates to REST APIs:

```bash
# Get date variables
eval "$(./scripts/datetime.sh)"

# Query an API with ISO date
curl "https://api.example.com/events?date=${DATE_ISO}"

# Send JSON with ISO datetime and timezone
curl -X POST https://api.example.com/logs \
  -H "Content-Type: application/json" \
  -d "{\"timestamp\": \"${DATETIME_ISO}\", \"message\": \"System check\"}"

# Use Unix timestamp for time-based APIs
curl "https://api.example.com/data?since=${TIMESTAMP_UNIX}"
```

### 3. Structured Data with Timestamps

Embed timestamps in JSON, CSV, or other structured formats:

```bash
eval "$(./scripts/datetime.sh)"

# Create JSON with multiple timestamp formats
cat > event.json <<EOF
{
  "event_id": "evt_${TIMESTAMP_UNIX}",
  "created_at": "${DATETIME_ISO}",
  "created_at_utc": "${DATETIME_UTC}",
  "date": "${DATE_ISO}",
  "display_date": "${DATE_HUMAN}",
  "timezone": "${TIMEZONE}"
}
EOF

# Append to CSV log
echo "${DATE_ISO},${TIMESTAMP_UNIX},system_check,OK" >> system_log.csv
```

### 4. Automated Backup Scripts

Create daily or periodic backups with organized naming:

```bash
#!/usr/bin/env bash
# Daily backup script

eval "$(./scripts/datetime.sh)"

# Define backup directory with date
BACKUP_DIR="backups/${DATE_ISO}"
mkdir -p "$BACKUP_DIR"

# Backup files with timestamps
tar -czf "${BACKUP_DIR}/data-${DATETIME_FILE}.tar.gz" /path/to/data
tar -czf "${BACKUP_DIR}/config-${DATETIME_FILE}.tar.gz" /etc/myapp

# Log the backup
echo "[${DATETIME_ISO}] Backup completed successfully" >> backup.log

# Cleanup old backups (keep last 7 days)
find backups/ -type d -mtime +7 -exec rm -rf {} +
```

### 5. Log File Management

Create and append to timestamped log files:

```bash
eval "$(./scripts/datetime.sh)"

# Create daily log file
LOGFILE="logs/app-${DATE_COMPACT}.log"

# Append entries with ISO timestamps
echo "[${DATETIME_ISO}] Application started" >> "$LOGFILE"
echo "[${DATETIME_ISO}] Connected to database" >> "$LOGFILE"

# Create a log entry function
log_message() {
  eval "$(./scripts/datetime.sh)"
  echo "[${DATETIME_ISO}] $1" >> "$LOGFILE"
}

log_message "Processing batch job"
log_message "Batch job completed"
```

### 6. Scheduling and Time-Based Operations

Use timestamps for scheduling decisions and time-based logic:

```bash
eval "$(./scripts/datetime.sh)"

# Check if it's time for maintenance (compare Unix timestamps)
LAST_MAINTENANCE=$(cat last_maintenance.txt)
TIME_SINCE=$((TIMESTAMP_UNIX - LAST_MAINTENANCE))
TWENTY_FOUR_HOURS=86400

if [ $TIME_SINCE -ge $TWENTY_FOUR_HOURS ]; then
  echo "Running maintenance..."
  ./maintenance.sh
  echo "$TIMESTAMP_UNIX" > last_maintenance.txt
fi

# Create time-based directory structure
ARCHIVE_DIR="archives/${DATE_ISO:0:4}/${DATE_ISO:5:2}"  # YYYY/MM
mkdir -p "$ARCHIVE_DIR"
mv processed_*.dat "$ARCHIVE_DIR/"
```

## Tips & Best Practices

### Format Selection Guide

- **Use `DATE_ISO`** for simple dates, database date fields, and when you don't need time information
- **Use `DATETIME_ISO`** when you need precise timestamps with timezone awareness (most common for logging)
- **Use `DATETIME_UTC`** for distributed systems, international applications, or when coordinating across timezones
- **Use `TIMESTAMP_UNIX`** for time calculations, sorting by time, or APIs that expect Unix timestamps
- **Use `DATE_HUMAN`** only for user-facing output, never for file names or database storage
- **Use `DATETIME_FILE`** for file and directory names (no colons or spaces, safe on all platforms)
- **Use `DATE_COMPACT`** when you need short date identifiers or daily grouping

### Timezone Considerations

- All timestamps except `DATETIME_UTC` reflect your system's local timezone
- The `TIMEZONE` variable shows your current offset from UTC
- Always use `DATETIME_UTC` when storing timestamps that will be accessed from multiple timezones
- For local operations (backups, logs), local time formats are usually more intuitive

### Performance Notes

- The script runs in under 10ms on most systems
- Call once and reuse variables rather than calling multiple times in loops
- For high-frequency logging, consider calling once per batch rather than per log entry

### Integration Patterns

```bash
# Pattern 1: Load once, use multiple times
eval "$(./scripts/datetime.sh)"
process_data "$DATE_ISO"
create_backup "$DATETIME_FILE"
log_event "$DATETIME_ISO"

# Pattern 2: Inline for simple cases
BACKUP_FILE="backup-$(./scripts/datetime.sh | grep DATE_ISO | cut -d= -f2).tar.gz"

# Pattern 3: Source in functions
get_timestamp() {
  eval "$(./scripts/datetime.sh)"
  echo "$DATETIME_ISO"
}
```

## Troubleshooting

### Permission Denied

If you get a "Permission denied" error:

```bash
chmod +x ./scripts/datetime.sh
```

### Script Not Found

If running from a different directory:

```bash
# Use absolute path
eval "$(/absolute/path/to/scripts/datetime.sh)"

# Or change to skill directory first
cd /path/to/current-date-and-time-skill
eval "$(./scripts/datetime.sh)"
```

### Date Command Differences

This script is compatible with both BSD date (macOS) and GNU date (Linux). If you experience issues:

- **macOS/BSD date**: Already compatible, no changes needed
- **Linux/GNU date**: Already compatible, no changes needed
- **Other systems**: May need to install GNU coreutils

### Timezone Formatting Issues

If timezone appears without colon (e.g., `+0800` instead of `+08:00`):

This shouldn't happen with the current script, but if you see it, ensure the sed command is working:

```bash
date '+%z' | sed -E 's/([+-][0-9]{2})([0-9]{2})$/\1:\2/'
```

### Empty or Missing Variables

If variables are empty after `eval`:

```bash
# Check script output directly
./scripts/datetime.sh

# Verify eval syntax (note the double quotes and dollar-parentheses)
eval "$(./scripts/datetime.sh)"

# Check if variables are set
echo "DATE_ISO is: ${DATE_ISO:-NOT SET}"
```

### Time Appears Incorrect

The script uses your system time. To verify:

```bash
# Check system time
date

# Check timezone setting
date +%Z

# For UTC time specifically
date -u
```

## Examples in Practice

### Complete Backup Script

```bash
#!/usr/bin/env bash
set -euo pipefail

# Load datetime variables
eval "$(./scripts/datetime.sh)"

# Configuration
SOURCE_DIR="/var/www/html"
BACKUP_ROOT="/backups"
BACKUP_DIR="${BACKUP_ROOT}/${DATE_ISO}"
LOGFILE="${BACKUP_ROOT}/backup.log"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Create backup with timestamp
BACKUP_FILE="${BACKUP_DIR}/website-${DATETIME_FILE}.tar.gz"
tar -czf "$BACKUP_FILE" "$SOURCE_DIR"

# Log success
echo "[${DATETIME_ISO}] Backup created: ${BACKUP_FILE}" >> "$LOGFILE"

# Cleanup old backups (keep 30 days)
find "$BACKUP_ROOT" -type f -name "*.tar.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_FILE"
```

### API Integration Script

```bash
#!/usr/bin/env bash

# Load datetime variables
eval "$(./scripts/datetime.sh)"

# API configuration
API_URL="https://api.example.com/metrics"
API_KEY="your-api-key"

# Send metrics with timestamp
curl -X POST "$API_URL" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"timestamp\": \"${DATETIME_ISO}\",
    \"timestamp_unix\": ${TIMESTAMP_UNIX},
    \"metric\": \"cpu_usage\",
    \"value\": 45.2,
    \"timezone\": \"${TIMEZONE}\"
  }"
```

## License

MIT License - See LICENSE.txt for details.

## Version

1.0.0 - Initial release with 8 essential date/time formats