From 1876a4de0d45c2c55f39ecc31199c16623b014b5 Mon Sep 17 00:00:00 2001
From: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date: Sat, 29 Nov 2025 18:03:09 +0800
Subject: [PATCH] Initial commit

---
 .claude-plugin/plugin.json              |  15 ++
 README.md                               |   3 +
 commands/calc.md                        | 129 ++++++++++
 commands/now.md                         |  92 ++++++++
 commands/parse.md                       | 135 +++++++++++
 plugin.lock.json                        |  61 +++++
 skills/datetime/SKILL.md                |  93 ++++++++
 skills/datetime/references/reference.md | 302 ++++++++++++++++++++++++
 8 files changed, 830 insertions(+)
 create mode 100644 .claude-plugin/plugin.json
 create mode 100644 README.md
 create mode 100644 commands/calc.md
 create mode 100644 commands/now.md
 create mode 100644 commands/parse.md
 create mode 100644 plugin.lock.json
 create mode 100644 skills/datetime/SKILL.md
 create mode 100644 skills/datetime/references/reference.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..c9b982d
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "datetime",
+  "description": "Natural language date/time parsing and calculations using native date command",
+  "version": "1.1.0",
+  "author": {
+    "name": "Mae Capacite",
+    "email": "cadrianmae@users.noreply.github.com"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0eec821
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# datetime
+
+Natural language date/time parsing and calculations using native date command
diff --git a/commands/calc.md b/commands/calc.md
new file mode 100644
index 0000000..fbadeed
--- /dev/null
+++ b/commands/calc.md
@@ -0,0 +1,129 @@
+---
+description: Calculate date/time differences (Claude should use date command directly)
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# calc - Calculate date/time differences
+
+Calculate the difference between two dates or times using natural language expressions.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use unix timestamp arithmetic via Bash tool:
+
+```bash
+date1=$(date -d "first date" +%s)
+date2=$(date -d "second date" +%s)
+diff=$((date2 - date1))
+echo "Difference: $diff seconds"
+```
+
+See the Implementation section below for the full calculation pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:calc
+```
+
+The command will interactively ask for two date/time expressions, then calculate the difference.
+
+## What it does
+
+1. **Asks for first date/time**: Accepts natural language expression (e.g., "tomorrow", "2024-12-01", "next Monday")
+2. **Asks for second date/time**: Accepts natural language expression
+3. **Calculates difference**: Shows the time between the two dates in multiple units
+4. **Human-readable output**: Displays results as days, hours, minutes, and seconds
+
+The calculation uses unix timestamps internally for accuracy across timezones and DST boundaries.
+
+## Implementation
+
+**Convert dates to unix timestamps:**
+```bash
+date1_ts=$(date -d "first expression" +%s)
+date2_ts=$(date -d "second expression" +%s)
+```
+
+**Calculate difference:**
+```bash
+diff_seconds=$((date2_ts - date1_ts))
+diff_days=$((diff_seconds / 86400))
+diff_hours=$(((diff_seconds % 86400) / 3600))
+diff_minutes=$(((diff_seconds % 3600) / 60))
+diff_secs=$((diff_seconds % 60))
+```
+
+**Display result:**
+```bash
+echo "Difference: ${diff_days}d ${diff_hours}h ${diff_minutes}m ${diff_secs}s"
+echo "Total: ${diff_seconds} seconds"
+```
+
+## Examples
+
+```bash
+# Days until deadline
+/datetime:calc
+→ First date/time: today
+→ Second date/time: 2024-12-15
+→ Difference: 32d 0h 0m 0s (32 days)
+→ Total: 2764800 seconds
+
+# Time since event
+/datetime:calc
+→ First date/time: 2024-11-01
+→ Second date/time: today
+→ Difference: 12d 0h 0m 0s (12 days)
+→ Total: 1036800 seconds
+
+# Hours between meetings
+/datetime:calc
+→ First date/time: today 14:00
+→ Second date/time: tomorrow 10:30
+→ Difference: 0d 20h 30m 0s
+→ Total: 73800 seconds
+
+# Working days remaining
+/datetime:calc
+→ First date/time: today
+→ Second date/time: next Friday
+→ Difference: 2d 0h 0m 0s (2 days)
+→ Total: 172800 seconds
+```
+
+## Common calculations
+
+**Academic deadlines:**
+- "today" to "2024-12-20" - Days until assignment due
+- "today" to "next Friday 23:59" - Time to weekly submission
+
+**Project milestones:**
+- "2024-11-13" to "2024-12-01" - Sprint duration
+- "last Monday" to "today" - Week progress
+
+**Event planning:**
+- "today" to "25 Dec" - Days until event
+- "9:00" to "17:00" - Meeting duration (same day)
+
+**Time tracking:**
+- "yesterday" to "today" - Daily intervals
+- "1 week ago" to "today" - Weekly reviews
+
+## When to use
+
+- Calculate days remaining until assignment deadlines
+- Track time elapsed on projects or sprints
+- Plan event schedules and milestones
+- Verify working time between meetings
+- Calculate age or duration of events
+- Estimate remaining time for deliverables
+- Academic semester/week planning
+
+## Related commands
+
+- `/datetime:now` - Get current date/time
+- `/datetime:parse` - Parse natural language date expressions
diff --git a/commands/now.md b/commands/now.md
new file mode 100644
index 0000000..44cb999
--- /dev/null
+++ b/commands/now.md
@@ -0,0 +1,92 @@
+---
+description: Get current date and time (Claude should use date command directly)
+argument-hint: [format]
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# now - Get current date and time
+
+Get the current date and time in a standardized format.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use the `date` command directly via Bash tool:
+
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+See the Implementation section below for the exact command pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:now
+/datetime:now [format]
+```
+
+## What it does
+
+1. **No arguments**: Returns current date/time in standard format
+   - Format: `YYYY-MM-DD HH:MM:SS (DayName)`
+   - Example: `2024-11-13 16:45:30 (Wednesday)`
+
+2. **With format argument**: Returns current date/time in custom format
+   - Uses `date` command format strings
+   - Example: `/datetime:now "%B %d, %Y"` → `November 13, 2024`
+
+## Implementation
+
+**Standard format:**
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Custom format:**
+```bash
+date '+[format-string]'
+```
+
+## Common format strings
+
+- `%Y-%m-%d` - Date only (2024-11-13)
+- `%H:%M:%S` - Time only (16:45:30)
+- `%A` - Full day name (Wednesday)
+- `%B %d, %Y` - Formatted date (November 13, 2024)
+- `%V` - Week number (45)
+- `+%s` - Unix timestamp (1699896330)
+
+## Examples
+
+```bash
+# Standard output
+/datetime:now
+→ 2024-11-13 16:45:30 (Wednesday)
+
+# Custom format - date only
+/datetime:now "%Y-%m-%d"
+→ 2024-11-13
+
+# Week number
+/datetime:now "%V"
+→ 45
+
+# Unix timestamp
+/datetime:now "+%s"
+→ 1699896330
+```
+
+## When to use
+
+- Verify current date/time before making temporal decisions
+- Get current week number for academic week mapping
+- Generate timestamps for logging or calculations
+- When <env> context date may be outdated
+
+## Related commands
+
+- `/datetime:parse` - Parse natural language date expressions
+- `/datetime:calc` - Calculate date differences
diff --git a/commands/parse.md b/commands/parse.md
new file mode 100644
index 0000000..71e98e6
--- /dev/null
+++ b/commands/parse.md
@@ -0,0 +1,135 @@
+---
+description: Parse natural language date/time expressions (Claude should use date command directly)
+argument-hint: <expression> [format]
+allowed-tools: Bash
+disable-model-invocation: true
+---
+
+# parse - Parse natural language date/time expressions
+
+Parse natural language date and time expressions into standardized format.
+
+## For Claude Code
+
+**If you are Claude**: DO NOT invoke this slash command. Use the `date` command directly via Bash tool:
+
+```bash
+date -d "expression" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+See the Implementation section below for the exact command pattern.
+
+## For Users
+
+### Usage
+
+```bash
+/datetime:parse <expression>
+/datetime:parse <expression> [format]
+```
+
+## What it does
+
+1. **Standard format**: Parses natural language and returns standardized date/time
+   - Format: `YYYY-MM-DD HH:MM:SS (DayName)`
+   - Example: `/datetime:parse "tomorrow"` → `2025-11-14 00:00:00 (Friday)`
+
+2. **Custom format**: Parse and return in custom format
+   - Uses `date` command format strings
+   - Example: `/datetime:parse "next Monday" "%Y-%m-%d"` → `2025-11-17`
+
+## Implementation
+
+**Standard format:**
+```bash
+date -d "<expression>" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Custom format:**
+```bash
+date -d "<expression>" '+[format-string]'
+```
+
+**Important: "in" prefix handling**
+- User says: "in 3 days"
+- Command needs: `date -d "3 days"`
+- Strip "in" prefix before passing to `date -d`
+
+## Natural language expressions
+
+**Relative dates:**
+- `tomorrow`, `yesterday`
+- `3 days`, `2 weeks`, `1 month`, `6 months`
+- `next Monday`, `last Friday`
+- `next week`, `last month`
+
+**Specific dates:**
+- `Nov 13`, `November 13`, `13 Nov 2025`
+- `2025-11-13`, `13/11/2025`
+
+**Combined expressions:**
+- `tomorrow at 3pm` → `2025-11-14 15:00:00 (Friday)`
+- `next Monday at 14:30` → `2025-11-17 14:30:00 (Monday)`
+- `3 days at noon` → `2025-11-16 12:00:00 (Sunday)`
+
+**Week navigation:**
+- `monday`, `tuesday` (next occurrence)
+- `next monday`, `last tuesday`
+
+## Examples
+
+```bash
+# Tomorrow
+/datetime:parse "tomorrow"
+→ 2025-11-14 00:00:00 (Friday)
+
+# Relative days (strip "in" if present)
+/datetime:parse "3 days"
+→ 2025-11-16 00:00:00 (Sunday)
+
+# Next week day
+/datetime:parse "next Monday"
+→ 2025-11-17 00:00:00 (Monday)
+
+# With time
+/datetime:parse "tomorrow at 3pm"
+→ 2025-11-14 15:00:00 (Friday)
+
+# Specific date
+/datetime:parse "Nov 15"
+→ 2025-11-15 00:00:00 (Saturday)
+
+# Custom format - date only
+/datetime:parse "next week" "%Y-%m-%d"
+→ 2025-11-20
+
+# Unix timestamp for calculations
+/datetime:parse "3 days" "+%s"
+→ 1731715200
+```
+
+## Error handling
+
+If the expression is invalid, `date` will return an error:
+```bash
+date -d "invalid expression"
+→ date: invalid date 'invalid expression'
+```
+
+Common mistakes:
+- `in 3 days` → Remove "in", use `3 days`
+- `3d` → Use full words: `3 days`
+- `next week monday` → Use `next monday` or `monday next week`
+
+## When to use
+
+- ANY time user mentions dates, times, or temporal concepts
+- Converting user's natural language into concrete dates
+- Calculating deadlines from relative expressions
+- Validating date inputs before processing
+- Don't guess dates - always verify with this command
+
+## Related commands
+
+- `/datetime:now` - Get current date and time
+- `/datetime:calc` - Calculate date differences
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..7b65a44
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:cadrianmae/claude-marketplace:plugins/datetime",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "3e81a7b3707353c2a4e6803ef170e18317507e63",
+    "treeHash": "3e326de9f209fafbe76c3970031242bd8ee53c9181c699d6e6262157dd5dae6d",
+    "generatedAt": "2025-11-28T10:14:27.856151Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "datetime",
+    "description": "Natural language date/time parsing and calculations using native date command",
+    "version": "1.1.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "d9393800b8ae0048479a4672fe7dddc8f4fea987f7245c06d4f1422e0b67f076"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "06c5cee893e29df4acf483654288eafedc67c7d766b5c170ef53f168803fd3fc"
+      },
+      {
+        "path": "commands/calc.md",
+        "sha256": "c55f0c2f2cf3881140d5486db6183f0a0a387e7af0ee5fdee1b51d3c950caa07"
+      },
+      {
+        "path": "commands/parse.md",
+        "sha256": "bef5bca97a26083e6415300ed1d7056d49caf64fef86beb73ac004626b2b3e6e"
+      },
+      {
+        "path": "commands/now.md",
+        "sha256": "0969d2058b2b9c6bb04f1f9515ee0192744afd23f4d27782eeb13e7d11ee5d42"
+      },
+      {
+        "path": "skills/datetime/SKILL.md",
+        "sha256": "51345c8aa3f97c8d65299a176efc485e44a012734e328cb9388906802f9d8b57"
+      },
+      {
+        "path": "skills/datetime/references/reference.md",
+        "sha256": "83a8ecc1430759a7ac1073153545459fd8c64e21b8e4c0f56013bcf2790f32c2"
+      }
+    ],
+    "dirSha256": "3e326de9f209fafbe76c3970031242bd8ee53c9181c699d6e6262157dd5dae6d"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/skills/datetime/SKILL.md b/skills/datetime/SKILL.md
new file mode 100644
index 0000000..118f05b
--- /dev/null
+++ b/skills/datetime/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: datetime
+description: Use the `date` command via Bash tool whenever you or the user mention time, dates, or temporal concepts. Verify current date/time before ANY temporal response, as environment context may be outdated. Parse expressions like "tomorrow", "next week", "3 days", "in 2 weeks", "next Monday at 3pm". Proactively invoke for deadlines, schedules, time-sensitive tasks, week numbers, or any date/time reference.
+allowed-tools: Bash
+---
+
+# DateTime Natural Language Parser
+
+Parse natural language date and time expressions using GNU `date` command (native Linux utility).
+
+## IMPORTANT: For Claude Code
+
+**DO NOT invoke slash commands** (`/datetime:parse`, `/datetime:now`, `/datetime:calc`) - those are for users only.
+
+**Instead, use the `date` command directly via the Bash tool:**
+
+```bash
+# Get current date/time
+date '+%Y-%m-%d %H:%M:%S (%A)'
+
+# Parse natural language
+date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
+date -d "next monday at 9am" '+%Y-%m-%d %H:%M:%S (%A)'
+date -d "3 days" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+This skill provides the command patterns and when to use them. The slash commands are for users to invoke manually.
+
+## When to Use This Skill
+
+Automatically invoke when:
+- User mentions temporal expressions: "tomorrow", "next week", "in 3 days"
+- Need to verify current date/time
+- User references deadlines or time-sensitive tasks
+- <env> context shows incorrect dates
+
+## How to Use
+
+Use the Bash tool with `date -d` command:
+
+**Get current date/time:**
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Parse natural language:**
+```bash
+date -d "tomorrow" '+%Y-%m-%d %H:%M:%S (%A)'
+date -d "next wednesday" '+%Y-%m-%d %H:%M:%S (%A)'
+date -d "3 days" '+%Y-%m-%d %H:%M:%S (%A)'
+date -d "next monday 9am" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+**Important**: The `date` command doesn't understand "in" keyword. When user says "in 3 days", use `"3 days"` instead.
+
+## Output Format
+
+Returns single line: `YYYY-MM-DD HH:MM:SS (DayName)`
+
+Example: `2024-10-29 14:23:45 (Tuesday)`
+
+## Supported Expressions
+
+- Relative: "today", "tomorrow", "yesterday"
+- Named days: "next monday", "this wednesday", "last friday"
+- Offsets: "3 days", "2 weeks", "5 months ago"
+- Complex: "tomorrow 3pm", "next monday at 9am"
+- Past: "3 days ago", "last week"
+
+## Error Handling
+
+If `date -d` fails with an invalid expression:
+
+1. **Recognize the failure**: If the command returns an error, inform the user the expression couldn't be parsed
+2. **Try alternative approaches**: Check `references/reference.md` for:
+   - Date arithmetic examples (if user wants relative calculations)
+   - Complex expression syntax (if user wants compound dates)
+   - Unix timestamp calculations (if user wants day differences)
+3. **Fallback to current date**: If no alternative works:
+   ```bash
+   date '+%Y-%m-%d %H:%M:%S (%A)'
+   ```
+
+**Example error handling:**
+```bash
+# Try parsing
+date -d "user expression" '+%Y-%m-%d %H:%M:%S (%A)' 2>&1
+# If error message appears, tell user and suggest checking references/reference.md for advanced patterns
+```
+
+## Advanced Usage
+
+For relative calculations, week numbers, and complex date arithmetic, see `references/reference.md`.
diff --git a/skills/datetime/references/reference.md b/skills/datetime/references/reference.md
new file mode 100644
index 0000000..bd7c49f
--- /dev/null
+++ b/skills/datetime/references/reference.md
@@ -0,0 +1,302 @@
+# 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
+
+```bash
+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:
+```bash
+'+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+Output: `2025-11-06 14:30:00 (Wednesday)`
+
+## Natural Language Parsing Examples
+
+### Current Time
+
+```bash
+date '+%Y-%m-%d %H:%M:%S (%A)'
+# → 2025-11-06 14:30:00 (Wednesday)
+```
+
+### Relative Dates
+
+```bash
+# 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"`
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# User: "I have a deadline on Tuesday"
+date -d "next tuesday" '+%Y-%m-%d %H:%M:%S (%A)'
+```
+
+### Pattern 3: Calculate Relative Dates
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+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