# Query Taiwan Holiday

> Query Taiwan holiday or workday status for a specific date. Automatically adapts to the caller's environment, falling through an already-installed `holidaytw`, the official install.sh/install.ps1, and finally the HTTPS static JSON API, reporting failure only once every trusted candidate has failed. Use for date-specific holiday questions, automation or scheduling checks, and requests for structured Taiwan holiday data.

- Skill: `doggy8088/query-taiwan-holiday-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add doggy8088/query-taiwan-holiday-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doggy8088/query-taiwan-holiday-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: doggy8088 (https://skillmd.com/u/doggy8088)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/doggy8088/query-taiwan-holiday-2

---


# Query Taiwan Holiday

> This is a concise, repository-scoped copy. The canonical, fully detailed version of this
> skill lives at the repository root: [`skill/SKILL.md`](../../../skill/SKILL.md). Both
> describe the same query/interpret/failure-handling behavior; prefer whichever copy the
> host surfaces.

## Query

1. Require one exact ASCII ISO date (`YYYY-MM-DD`). Reject whitespace, timestamps, slashes, impossible dates, and values that do not round-trip through a calendar-aware date parser.
2. Try trusted candidates in order, falling through to the next on failure rather than stopping: (a) an already-installed `holidaytw` on `PATH`; (b) when Node.js 20 or newer and npm are available, `npx --yes holidaytw --json YYYY-MM-DD` from the officially published npm package; (c) the official `install.sh` one-liner on macOS/Linux or `install.ps1` on Windows PowerShell, then re-resolving the installed path (`PATH`, or the default/`--dir`/`-InstallDir` location) if it is not yet on `PATH`. The npm wrapper downloads the matching native binary from the official GitHub Release and verifies `checksums.txt`. A failed candidate is not a final failure — it only means try the next one, which (including the API fallback below) may still return valid data. Only use official sources: the `holidaytw` npm package, `github.com/doggy8088/holidaybook`, `raw.githubusercontent.com/doggy8088/holidaybook`, and `https://holiday.gh.miniasp.com`.
3. Query with the resolved CLI for structured output:

   ```sh
   holidaytw --json YYYY-MM-DD
   ```

   Use `holidaytw YYYY-MM-DD` for a concise human-readable answer. Add `--base-url https://mirror.example` to either form when a trusted mirror is required.
4. If every candidate in step 2 failed or is unsupported here (no network, unsupported OS/arch, sandboxed shell, permission errors), fall back to the validated date against the static API:

   ```sh
   curl --fail-with-body --silent --show-error --location \
     --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 30 \
     'https://holiday.gh.miniasp.com/YYYY-MM-DD.json'
   ```

   Substitute only the already validated date; keep the URL quoted. Do not disable TLS verification.
5. Parse JSON rather than scraping text. Require one object, a matching `date` (the API may use `YYYYMMDD`), and a present, recognized `isHoliday` value.

## Interpret

- Treat `isHoliday: true` or `1` as a holiday.
- Treat `isHoliday: false` or `0` as a workday.
- Do not infer status from weekday/weekend alone; Taiwan can designate weekend workdays (`補行上班日`) and compensatory holidays.
- The two sources use different field shapes for the same data:
  - `holidaytw --json`: `date` is `YYYY-MM-DD`, `isHoliday` is a boolean, and the category field is `category`.
  - Static JSON (`https://holiday.gh.miniasp.com/YYYY-MM-DD.json`): `date` is `YYYYMMDD`, `isHoliday` is `0`/`1`, and the category field is `holidaycategory`.
- Preserve useful structured fields: `date`, `name`, the category field for that source, and `description`. Workdays can also carry them (for example 軍人節 is `isHoliday` false with a name and description). For automation, return the raw or requested JSON shape instead of prose unless asked.
- Treat missing, null, or unrecognized `isHoliday` as unknown data, never as a workday.

## Handle failures

- A nonzero exit from any single trusted candidate (CLI, an installer script, or one `curl` attempt) is not, by itself, a reason to report failure — fall through to the next candidate per step 2. Only report retrieval failure and make no holiday-status claim once every candidate, including the static API fallback, has failed.
- CLI exit codes: `0` success, `2` bad arguments or invalid date, `1` runtime failure. With `--json`, failures print `{"error":{"code":"...","message":"..."}}` on stderr, where `code` is one of `usage`, `invalid_date`, `invalid_configuration`, `http_error`, `invalid_response`, `timeout`, `canceled`, `network_error`, `output_error`.
- Distinguish HTTP 404 or unavailable data from DNS, TLS, timeout, and other transport errors when stderr provides that detail.
- Reject malformed JSON, non-object responses, date mismatches, and missing required fields explicitly.
- Never silently substitute a nearby date or guess from the calendar.