temporal-awareness: Make Claude Code Actually Know What Day It Is

A SKILL.md file that teaches Claude Code to run the real date command when it needs to reason about time—instead of guessing from a session-start timestamp that may already be wrong.

The Gap It Fills

Claude Code gets a current date in its system prompt when a session starts. That's the extent of its temporal awareness. The date can be accurate, slightly stale, or missing entirely depending on how your client passes it over—and Claude has no way to tell which. So when you ask it to calculate working days to a deadline, verify whether a release date falls on a weekday, or reason about a cron schedule, it works backward from a fixed point that may already be off. temporal-awareness fixes this in the most direct way possible: it instructs Claude to actually run date when temporal reasoning is needed. GNU date on Linux, BSD date on macOS/FreeBSD—the skill detects the platform and picks the right variant. No config, no runtime dependencies.

The Honest Limitation

The skill trusts your system clock entirely—it just runs date and reads what comes back. That's fine on a local dev machine with a sensible timezone set. But if you're running Claude Code inside a Docker container, a GitHub Codespace, or WSL, the system clock might be UTC (or something else unexpected) rather than what your brain assumes. The skill doesn't expose a timezone override; it takes whatever $TZ gives it. Worth knowing before you rely on it for anything time-sensitive in a cloud or CI environment.

Install in Two Commands

Clone the repo and symlink the skill into your Claude skills directory:

git clone --branch latest git@github.com:hodgesmr/temporal-awareness.git ~/temporal-awareness
ln -sfn ~/temporal-awareness/skills/temporal-awareness ~/.claude/skills/temporal-awareness

After the symlink, Claude picks up the skill automatically—no restart required, no config file to edit.

Worth Adding

If you ever type "is Thursday a good day to deploy this?" or "how many business days until the 30th?" at Claude Code, this skill earns its place. It's small, zero-dependency, and quietly prevents a category of subtle errors that only surface when someone later checks the math in a handoff doc or a missed-deadline post-mortem. Built by Matt Hodges—the full repo is at github.com/hodgesmr/temporal-awareness, MIT licensed.