woolworths-nz - SKILL.md Agent Skill

name: woolworths-nz description: Query Woolworths NZ product search, specials, category browse, and SKU detail. Use for Woolworths NZ grocery prices, specials, and product lookup. Read-only; no trolley or checkout actions.

Woolworths NZ

Goal

Query live Woolworths NZ product data through a small deterministic CLI with human-readable and JSON output, without browser automation or account login.

Use this when

A user asks for Woolworths NZ product prices or specials
A user wants to search Woolworths products by keyword
A user has Woolworths SKUs and wants product details
A user needs lightweight machine-readable Woolworths product data
A workflow needs a fast read-only alternative to browser-driven Woolworths tooling

Do not use this for

Woolworths Australia or non-Woolworths retailers
Authenticated account, Everyday Rewards, personalised, delivery-slot, trolley, checkout, or order actions
Redistributing scraped Woolworths product data as a dataset
Historical pricing or price-change claims unless another dataset provides history

Preferred workflow

Run scripts/cli.py with the narrowest subcommand that answers the task
Use search for keyword price/product lookup and specials for promotional products
Use product when exact SKUs are known
Use browse only when a numeric category id is known from product/category data
Use --json for agent chaining, comparisons, or structured reports
Mention that prices are live online Woolworths snapshots and the source is unofficial

CLI

Run with:

python3 skills/woolworths-nz/scripts/cli.py <command> [flags]

Commands

search <query> [--limit N] [--page N] [--size text] [--in-stock-only] [--json] — product search with prices
specials [query] [--limit N] [--page N] [--in-stock-only] [--json] — promotional products
browse <category-id> [--limit N] [--page N] [--in-stock-only] [--json] — browse a known numeric category id
product <sku...> [--json] — fetch exact product SKUs

Examples:

python3 skills/woolworths-nz/scripts/cli.py search milk --limit 10
python3 skills/woolworths-nz/scripts/cli.py search "wholemeal bread" --limit 5 --json
python3 skills/woolworths-nz/scripts/cli.py specials cheese --limit 10 --json
python3 skills/woolworths-nz/scripts/cli.py product 705692 --json

Resources

CLI entrypoint: scripts/cli.py
Live smoke test: scripts/smoke_test.py
API and stability notes: references/api-notes.md

Notes

No API key, username, password, account cookie, or browser automation is required for read-only product lookup
This is intentionally lighter than browser/login-based Woolworths CLIs: Python stdlib only, public GET endpoints only
Endpoint shapes can change; verify with a small live query before relying on large workflows
The upstream inspiration repo is MIT-licensed, but this skill is a clean lightweight standalone implementation focused on public read-only product endpoints