🏨 Hotel Booking Assistant

An Agent Skill that researches, compares, and shortlists hotels from current, like-for-like evidence — and prepares the booking decision without ever booking for you.

tests License: MIT Python 3.9+ Dependencies: stdlib only

Features • Installation • Quick start • How it works • 日本語

A report generated from the bundled synthetic sample data — no real hotels were harmed.

hotel-booking-assistant is an Agent Skill for Claude Code and other skill-aware agents. Ask "find me a hotel near Kyoto Station, Nov 10–13, two adults" and it researches candidates with current web evidence, normalizes prices into full-stay totals, compares booking sites like-for-like, and delivers an evidence-backed HTML shortlist with explicit tradeoffs — not an opaque score, and never a reservation made on your behalf.

Features

  • Current evidence only — prices, availability, and policies are researched for your exact dates, occupancy, and room count, with a capture time and source URL on every volatile fact.
  • Like-for-like totals — full-stay totals compared under the same dates, occupancy, currency, and tax basis; cross-currency and mismatched offers are marked incomparable instead of silently mixed.
  • Three judgments kept separate — property quality, booking-site/offer choice, and meal-plan value never blur into one number.
  • Independent review families — mirrored ratings across affiliated sites are counted once, and small or dependent samples reduce stated confidence.
  • Honest uncertainty — blocked, stale, login-only, or search-result-only evidence is labeled as such, never estimated.
  • Meal-plan deltas done right — room-only vs. breakfast compared only when every other material condition matches.
  • Neutral by default — no assumed memberships, coupons, or card perks; benefits are included only when you confirm them.
  • Prompt-injection aware — fetched pages and supplied datasets are treated as untrusted data; embedded instructions are recorded, not obeyed.

Safety by design

The skill prepares booking decisions and can walk you through your own booking one step at a time — but reservation, payment, cancellation, account changes, and personal-data entry are always user-performed. It never transacts and never enters payment or personal data autonomously.

Installation

Claude Code — clone into your personal skills directory:

git clone https://github.com/ran-net/hotel-booking-assistant.git ~/.claude/skills/hotel-booking-assistant

Or add it to a single project instead:

git clone https://github.com/ran-net/hotel-booking-assistant.git .claude/skills/hotel-booking-assistant

Claude discovers the skill automatically. Trigger it with requests like "find me a hotel …", "cheapest booking site for …", or "ホテルを探して".

Other frontends — the skill folder follows the standard SKILL.md layout, and agents/openai.yaml provides optional display metadata for OpenAI-style frontends.

Quick start

The bundled scripts run anywhere with Python 3.9+ — no third-party packages. Validate the synthetic sample data, then generate a standalone HTML report:

python scripts/validate_data.py examples/sample-hotels.json
python scripts/generate_report.py examples/sample-hotels.json hotel-report.html

Useful variations:

# Machine-readable validation results
python scripts/validate_data.py examples/sample-hotels.json --json

# Japanese report, custom template
python scripts/generate_report.py examples/sample-hotels.json hotel-report.html --locale ja
python scripts/generate_report.py examples/sample-hotels.json hotel-report.html --template assets/report-template.html

[!TIP] On Windows consoles, add -X utf8 (e.g. python -X utf8 scripts/validate_data.py …) if the active console encoding causes text or filename issues.

How it works

SKILL.md routes each request to the smallest workflow that satisfies it:

Route When What happens
Research from scratch "Find me a hotel in …" Broad candidate discovery → shortlist verification → report
Compare a shortlist "Compare these four hotels" Verifies the named properties under identical stay conditions
Analyze supplied data You already have JSON Validates the data, flags gaps, generates the report — no invented facts
Reservation requested "Book it" Research/compare first, then assists your booking one step at a time

Each route loads only the reference documents it needs (references/research-playbook.md, plan-comparison.md, scoring-and-recommendations.md, data-schema.md, report-spec.md), keeping the agent's context small.

Repository layout

Path Purpose
SKILL.md Agent entry point and workflow router
references/ Research playbook, plan comparison, scoring, report spec, data schema
scripts/validate_data.py Validates hotel-comparison JSON (--json for machine-readable output)
scripts/generate_report.py Generates a standalone HTML report from validated JSON
scripts/test_scripts.py Regression tests for both scripts
assets/report-template.html Default standalone HTML report template
examples/sample-hotels.json Synthetic sample input
evals/ Evaluation prompts and three synthetic fixtures
agents/openai.yaml Optional display metadata for OpenAI-style frontends
docs/ README assets

Development

All scripts use only the Python standard library. Run the regression suite (75 tests, also run in CI on Ubuntu/Windows × Python 3.9/3.13):

python scripts/test_scripts.py

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Keep scripts stdlib-only, keep the evidence rules intact, and keep all example data synthetic.

License

MIT