A high-precision time processing engine for AI agents focusing on Chinese lunar calendars, statutory holidays, and complex timezone conversions.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install truetime-cn
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install truetime-cn using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is truetime-cn?
truetime-cn is a robust, zero-dependency Python tool designed to solve the inherent inaccuracies AI models face when handling real-time data. While LLMs often struggle with drifting session times or lack awareness of specific regional calendars, this Openclaw Skills addition provides a definitive factual layer for time-sensitive decision-making. It supports Claude.ai sandboxes, Claude Code, and local environments, ensuring that your agent always has access to the ground truth of "now."
The skill excels at navigating the complexities of the Chinese calendar, including the 24 solar terms, Ganzhi cycles, and the unique statutory holiday system (including compensatory workdays). By offloading time math—such as calculating 1.5 months from a specific date or handling Daylight Saving Time (DST) ambiguities—to this dedicated script, developers ensure their AI agents provide reliable, production-grade scheduling and task management.
truetime-cn Use Cases
- Scheduling international meetings between Beijing and global timezones like New York or London.
- Calculating deadlines and countdowns for projects involving Chinese statutory holidays and adjusted workdays.
- Converting lunar calendar dates to Gregorian UTC for flight bookings or traditional festival planning.
- Managing long-running AI sessions where the initial system-injected timestamp has become obsolete.
- Validating precise intervals such as milliseconds or fractional months for technical automation.
How truetime-cn Works
- Intent Extraction: The agent identifies time-related keywords (e.g., "tomorrow," "Spring Festival," "1.5 months") from the user prompt.
- Script Execution: The agent calls the Python script with specific arguments like
--plusor--targetto retrieve a structured JSON response. - Fact-Checking: The skill bypasses the AI's internal clock and system-injected dates to read the actual current server and user time.
- Data Synthesis: The script processes lunar data, holiday JSON files, and timezone offsets to generate comprehensive metadata.
- UTC-First Reasoning: The agent uses the provided
target_utcfor all logical calculations and ordering to prevent timezone errors. - Localized Response: The final output is translated back into user-friendly formats like
target_user_tzorlunar.displayfor the conversation.
truetime-cn Setup
The truetime-cn skill requires Python 3.9 or higher and has no external dependencies. All necessary libraries, including cnlunar, are pre-vendored.
To run within an Openclaw Skills environment or locally:
# Get current Beijing time with human summary
python3 ./scripts/truetime_cn.py --human
# Calculate a target date 1.5 months in the future
python3 ./scripts/truetime_cn.py --plus 1.5month
# Perform timezone conversion
python3 ./scripts/truetime_cn.py --target 2026-09-25T09:00:00 --target-tz Asia/Shanghai --user-tz America/New_York
truetime-cn Data Schema & Taxonomy
The skill returns a strictly formatted JSON object. Key fields include:
| Field | Description |
|---|---|
target_utc |
Standardized ISO 8601 UTC timestamp. |
target_lunar |
Object containing display string (e.g., "丙午年三月廿二"), zodiac, and next_solar_term. |
target_is_workday |
Boolean indicating if the date is a working day (considering Chinese holiday shifts). |
target_zh_holiday |
The name of the Chinese statutory holiday, or null if none. |
holiday_data_year_available |
Boolean verifying if the specific year's holiday data is loaded. |
delta_human_zh |
A natural language summary of the time difference. |
truetime-cn Advanced Features
- Drift Detection: Automatic triggers to refresh time data if more than 15 minutes have passed in a conversation.
- DST Hard-Error Handling: Instead of guessing during DST overlaps, the skill returns a specific error to force explicit offset confirmation.
- Lunar Pinning: Supports complex lunar-to-solar conversions while maintaining UTC as the primary execution standard.
- Holiday Source Transparency: Identifies if a workday determination is based on official statutory data or standard weekend rules.
- Composite Token Support: Handles complex relative time strings such as
1h30mor1month2weekswith floating-point precision.
SKILL.md
Loading
Related Openclaw Skills
4K Editing with OpenShot
A cloud-powered AI video editing skill that automates 4K resolution exports, transitions, and cuts using natural language commands.
Glancely
Glancely is a personal tracker framework that scaffolds habit, mood, and task trackers from natural language into a unified dashboard.
Travel Disruption Rescue
A structured emergency response workflow designed to transform travel chaos into an actionable recovery plan for cancellations, delays, and lost baggage.
SEO Blog Planner
A strategic content planning tool that transforms ecommerce blogs into high-conversion sales funnels through keyword-driven topic clusters.
Browser Nemo Video
A powerful browser-based video editing skill that transforms raw clips into polished 1080p MP4 exports via simple text commands.
Document Structured Data Extraction
A sophisticated extraction tool that transforms unstructured documents into structured JSON data using custom-defined schemas for text, tables, and paragraphs.
Featured*
