School Terms NZ

Goal

Query the Ministry of Education's current public school terms and holidays page with a bounded, read-only, standard-library Python CLI.

Use This When

• A user asks for official New Zealand school term or school holiday dates.
• A workflow needs to identify the published term or break covering a date.
• A user wants the current or next published school break from a date.
• A user needs the current or past years published by the Ministry, with source provenance.

Do Not Use This For

• An individual school's exact opening, closing, teacher-only or local-event dates.
• Early childhood service or private-school calendars, which may set their own dates.
• Public-holiday entitlement advice or local anniversary dates.
• Historical dates outside the past-year sections currently published on the source page.

Preferred Workflow

1. List the Ministry's complete current and past published years:

   python3 skills/school-terms-nz/scripts/cli.py years --json
   

2. Inspect one complete published year:

   python3 skills/school-terms-nz/scripts/cli.py year 2026 --json
   

3. Classify an ISO date as a published term, break, school-dependent period or uncovered date:

   python3 skills/school-terms-nz/scripts/cli.py date 2026-04-10 --json
   

4. Find the current or next published break from an ISO date:

   python3 skills/school-terms-nz/scripts/cli.py next-break 2026-06-01 --json
   

5. Preserve source_url, fetched_at and provenance in any answer. Report certainty and caveat whenever school dates vary.

All data commands accept --timeout SECONDS (integer range 1–120; default 10) and --json.

Interpretation Rules

• Terms 2 and 3 use the fixed dates published by the Ministry.
• Schools have flexibility over Term 1 opening and Term 4 closing dates. During either variable window, date returns school_term_or_break with certainty: "school_dependent" rather than claiming a definite term or break.
• Published inter-term breaks are returned as fixed ranges. Summer holidays begin on each school's closing date, no later than the published boundary; the skill does not reproduce the source's narrative duration wording.
• Weekends, teacher-only days, public holidays, local anniversary days and emergency closures can close a school during a term; this CLI does not infer those local closures.
• next-break returns the current break when the query date is already inside one; otherwise it returns the next break represented by the published years.
• Inside the inclusive Term 1 opening window, next-break cannot know whether an individual school is still on summer holiday or has opened. The usual top-level envelope remains unchanged, but break has certainty: "school_dependent", days_until: null, an individual-school-calendar caveat, and next_fixed_break with name, start, end and days_until for the next universally published break. Dates before the earliest opening remain current summer holiday results; when no preceding-year Summer holidays section is published, that result uses certainty: "source_derived" plus an explicit provenance caveat. Dates after the latest opening use the usual certain next-break shape.
• During Term 4, the Ministry publishes only a no-later-than closing boundary. next-break therefore returns summer holidays with certainty: "school_dependent" and days_until: null until the latest possible closing day has passed; use the individual school's calendar for an exact countdown.

Errors

• Exit 2: invalid ISO date, timeout outside the documented 1–120 second range, invalid timeout option/value or unpublished year.
• Exit 4: source access blocked or rate-limited.
• Exit 5: upstream source unavailable, including an upstream request timeout.
• Exit 6: Ministry page schema changed or published sections are incomplete.

Errors are concise and emit structured JSON when --json is supplied. Date inputs are validated before any network request. The CLI never writes to the source or local user files.

Source Attribution and Content Licence

The date and opening-count facts come from the New Zealand Ministry of Education's School terms and holidays page. Returned descriptions are independently generated from parsed dates and counts; source paragraphs and public-holiday prose are not redistributed.

The license: MIT field applies only to this skill's original code and documentation. Fetched Ministry content remains subject to the source site's terms, including its CC BY-NC 4.0 and Crown copyright notices; this skill does not relicense that source content. Every successful command includes this boundary in its provenance object and human-readable output.

Resources

• CLI: scripts/cli.py
• Deterministic contract check: scripts/test_contract.py
• Fixture and bounded live smoke: scripts/smoke_test.py
• Source and parser details: references/source-notes.md