time-filtered-queries

Converts natural-language time expressions into UTC date ranges for calendar, email, and task queries.

Updated Jul 10, 2026
One-click install
npx skills add https://github.com/timchap/dot-hermes --skill time-filtered-queries-timchap
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: time-filtered-queries
Source: https://github.com/timchap/dot-hermes/tree/main/skills/time-filtered-queries
Command: npx skills add https://github.com/timchap/dot-hermes --skill time-filtered-queries-timchap

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Queries like "show my meetings this week" or "emails from the past 7 days" fail when the AI guesses the current date or misinterprets week boundaries. This Skill establishes the correct date range from the system clock before constructing any query, eliminating wrong-date results across calendar, email, and task tools. ## Core Features & Use Cases - System-clock grounding: Always runs the date command first so the current date is never inferred from emails, events, or conversation context. - Time expression parsing: Maps phrases like "today", "this week" (ISO Monday-start), "next week", and "past N days" into precise start/end boundaries. - RFC3339 UTC conversion: Produces correctly formatted time_min/time_max values for Google Calendar, after:/before: queries for Gmail, and in-code filtering for task lists. - Use Case: A user asks "What meetings do I have next week?" The Skill reads the system clock, computes the following Monday-to-Sunday window in UTC, calls the calendar API with those bounds, and displays results in the user's local timezone. ## Quick Start Ask the assistant to list all calendar events and emails from this week using the correct date range from the system clock.

Frequently Asked Questions about time-filtered-queries

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I filter calendar events by date range with an API?▼

Use the Google Calendar API's time_min and time_max parameters with RFC3339 UTC timestamps, where time_max is exclusive. Compute the range from the system clock first, then pass values like 2026-07-14T00:00:00Z to bound the query.

How to search Gmail emails from a specific time period?▼

Use Gmail search operators after:YYYY/MM/DD and before:YYYY/MM/DD in the query string, for example via gmail_mcp.search_threads. Derive the dates from the system clock rather than inferring them from message content.

Why do AI assistants return events for the wrong week?▼

Wrong-week results happen when the model infers the current date from conversation context or event data instead of the system clock. Running the date command first and using ISO Monday-start week boundaries fixes this.

Does this approach handle different timezones correctly?▼

Yes. API queries are always made in UTC with a Z suffix, and results are converted back to the user's local timezone for display. Google Calendar events include a native timeZone field used to show correct local times.

Can task lists be filtered by date the same way as calendars?▼

Not natively. Task tools like tasks_mcp.list_tasks have no built-in time filter, so results must be retrieved first and then filtered in code against the computed date range.