zhongwei/gh-cadrianmae-claude-marketplace-plugins-datetime
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1876a4de0d45c2c55f39ecc31199c16623b014b5
gh-cadrianmae-claude-market…/skills/datetime/references/reference.md
Zhongwei Li 1876a4de0d Initial commit
2025-11-29 18:03:09 +08:00

7.4 KiB
Raw Blame History

DateTime Natural - Technical Reference

For Claude Code

This reference is for technical details only. When you need to work with dates/times:

  1. DO NOT invoke slash commands (/datetime:parse, /datetime:now, /datetime:calc)
  2. DO use the date command directly via Bash tool as shown in examples below

The slash commands are for users only. This reference provides the command patterns you should use directly.

GNU date Command Reference

The date command is a native Linux utility that parses natural language date/time expressions without requiring external dependencies.

Basic Syntax

date [OPTION]... [+FORMAT]
date -d STRING [+FORMAT]
  • -d STRING: Display time described by STRING instead of 'now'
  • +FORMAT: Control the output format

Recommended Format String

Always use this format for consistency:

'+%Y-%m-%d %H:%M:%S (%A)'

Output: 2025-11-06 14:30:00 (Wednesday)

Natural Language Parsing Examples

Current Time

date '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-06 14:30:00 (Wednesday)

Relative Dates

# Tomorrow
date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 14:30:00 (Thursday)

# Yesterday
date -d "yesterday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-05 14:30:00 (Tuesday)

# Next week
date -d "next week" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-13 14:30:00 (Wednesday)

# Last week
date -d "last week" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-30 14:30:00 (Wednesday)

Offset Expressions

Important: Remove "in" prefix - user says "in 3 days" → use "3 days"

# User says "in 3 days" (remove "in")
date -d "3 days" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-09 14:30:00 (Saturday)

# 2 weeks
date -d "2 weeks" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-20 14:30:00 (Wednesday)

# 5 months
date -d "5 months" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-04-06 14:30:00 (Wednesday)

# Past dates
date -d "3 days ago" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-03 14:30:00 (Monday)

date -d "2 weeks ago" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-23 14:30:00 (Thursday)

Named Days

# Next monday
date -d "next monday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 14:30:00 (Monday)

# This wednesday
date -d "this wednesday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-12 14:30:00 (Wednesday)

# Last friday
date -d "last friday" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-10-31 14:30:00 (Friday)

Complex Expressions with Times

# Tomorrow at specific time
date -d "tomorrow 3pm" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 15:00:00 (Thursday)

# Next monday at 9am
date -d "next monday 9am" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 09:00:00 (Monday)

# Tomorrow at 3:30pm
date -d "tomorrow 15:30" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-07 15:30:00 (Thursday)

Relative Calculations

Date Arithmetic

# Calculate deadline: 3 days from tomorrow
date -d "tomorrow + 3 days" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-11-10 14:30:00 (Sunday)

# Calculate 2 weeks before a date
date -d "2025-12-25 - 2 weeks" '+%Y-%m-%d %H:%M:%S (%A)'
# → 2025-12-11 00:00:00 (Thursday)

# Add/subtract time units
date -d "now + 2 hours" '+%Y-%m-%d %H:%M:%S (%A)'
date -d "tomorrow - 3 hours" '+%Y-%m-%d %H:%M:%S (%A)'
date -d "next monday + 2 days" '+%Y-%m-%d %H:%M:%S (%A)'

Calculate Days Between Dates

# Calculate days until deadline
DEADLINE=$(date -d "Nov 13" +%s)
NOW=$(date +%s)
DAYS=$(( ($DEADLINE - $NOW) / 86400 ))
echo "$DAYS days remaining"
# → 7 days remaining

# Time between two specific dates (in days)
DATE1=$(date -d "2025-11-06" +%s)
DATE2=$(date -d "2025-11-13" +%s)
DIFF=$(( ($DATE2 - $DATE1) / 86400 ))
echo "$DIFF days between dates"
# → 7 days between dates

Note: +%s format gives Unix timestamp (seconds since epoch), then divide difference by 86400 (seconds in a day).

Week Number Calculations

Get Current Week Number

# ISO week number (1-53)
date +%V
# → 45

# Get week number for a specific date
date -d "2025-12-25" +%V
# → 52

Academic Week Mapping

Use in conjunction with project-specific week mapping scripts to translate calendar weeks to academic weeks:

# Get calendar week
CALENDAR_WEEK=$(date +%V)

# Map to academic week (example from tu856-4-claude)
ACADEMIC_WEEK=$(~/.claude/skills/week-mapping.sh)

Common Use Cases

Pattern 1: Verify Current Date Before Responding

# ALWAYS verify current date before responding with temporal information
date '+%Y-%m-%d %H:%M:%S (%A)'

Why: The <env> context may show incorrect dates, leading to wrong responses.

Example:

  • User asks: "When is next Friday?"
  • Action: Check current date first → Parse "next friday"

Pattern 2: Parse Deadline Mentions

# User: "I have a deadline on Tuesday"
date -d "next tuesday" '+%Y-%m-%d %H:%M:%S (%A)'

Pattern 3: Calculate Relative Dates

# User: "Is tomorrow a weekend?"
date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
# Check day name in output

Pattern 4: Calculate Days Until Event

# User: "How many days until November 13?"
DEADLINE=$(date -d "Nov 13" +%s)
NOW=$(date +%s)
DAYS=$(( ($DEADLINE - $NOW) / 86400 ))
echo "$DAYS days remaining"

Error Handling

Fallback Pattern

If date parsing fails, fall back to current date/time:

date -d "invalid expression" '+%Y-%m-%d %H:%M:%S (%A)' 2>/dev/null || date '+%Y-%m-%d %H:%M:%S (%A)'

This pattern:

  1. Attempts to parse the expression
  2. Suppresses error messages with 2>/dev/null
  3. Falls back to current date with || date ...

Common Parsing Issues

  1. "in X days" doesn't work: Remove "in" prefix

    • ❌ date -d "in 3 days"
    • ✅ date -d "3 days"

  2. Always quote expressions: Prevents shell parsing issues

    • ❌ date -d next monday
    • ✅ date -d "next monday"

  3. Use consistent format: Always use the recommended format string

    • ✅ '+%Y-%m-%d %H:%M:%S (%A)'

Format String Reference

The recommended format string components:

  • %Y: 4-digit year (2025)
  • %m: 2-digit month (01-12)
  • %d: 2-digit day (01-31)
  • %H: 2-digit hour, 24-hour format (00-23)
  • %M: 2-digit minute (00-59)
  • %S: 2-digit second (00-59)
  • %A: Full weekday name (Monday, Tuesday, etc.)

Other useful format codes:

  • %V: ISO week number (01-53)
  • %s: Unix timestamp (seconds since 1970-01-01 00:00:00 UTC)
  • %z: Timezone offset (+0100)
  • %Z: Timezone name (EST, PST, etc.)

Configuration

The date command uses:

  • Language: System locale (usually English)
  • Timezone: System timezone
  • Date handling: Correctly interprets "next" vs "this" for weekdays

ADHD/Neurodivergent Support

This skill is particularly useful for:

  • Track time meticulously for executive function support
  • Parse time mentions in user messages automatically
  • Verify temporal context when planning tasks
  • Support deadline tracking with natural language
  • Calculate available time between events

Version History

  • v3.0.0 (2025-11-06): Native GNU date command

    • Removed Python dependency entirely
    • Uses native Linux date command with -d flag
    • Progressive disclosure: moved technical details to reference.md
    • Lean SKILL.md with reference to this file

  • v2.0.0 (2025-10-29): Switched to parsedatetime

    • Replaced dateparser with parsedatetime for better "next/this" handling
    • Added isolated virtual environment for dependency management

  • v1.0.0 (2024-10-29): Initial Python version with dateparser

    • Migrated from Node.js/chrono-node to Python/dateparser
Reference in New Issue View Git Blame Copy Permalink