Browse documentation

Agent Skill

A free, open-source skill that teaches AI assistants how to use StayAPI — the right tool, the right parameters, the right order. Install it once and prompts like "pull every review since June into a spreadsheet" just work.

What an agent skill is

A skill is a folder of instructions — a SKILL.md plus reference files — that your AI assistant loads automatically when a matching task comes up. No runtime, no build step: it's portable markdown that works in Claude Code, Claude.ai, Claude Desktop, and any other skills-aware agent.

The StayAPI skill encodes our workflows and the pitfalls that trip up agents: resolving destination IDs before searching, using sort=recent_desc for chronological review backfills, reporting Booking prices as stay totals rather than nightly rates, and never printing your API key.

Skill MCP server REST API
What it is The knowledge — workflows & gotchas The connection — 55 live tools The raw surface — plain HTTPS
Cost Free (MIT) 1 quota unit / call 1 quota unit / call
Best with Either of the other two Skill installed Scripts & backends

The skill and the MCP server pair: install both and your agent knows what to do and has the tools to do it. In Claude Code the skill can also drive the REST API directly from the shell using your STAYAPI_API_KEY environment variable.

Install

Claude Code

Run both commands inside a Claude Code session, then open a new session:

claude code 
/plugin marketplace add stayapi/agent-skill
/plugin install stayapi@stayapi

Claude.ai & Claude Desktop

  1. Download stayapi.skill from the latest GitHub release.
  2. Upload it under Settings → Capabilities → Skills.
  3. For live data on Claude.ai, also add the StayAPI MCP connector — the skill supplies the know-how, the connector supplies the tools.

Any other skills-aware agent

The skill is plain markdown — clone and copy it wherever your agent looks for skills:

bash 
git clone https://github.com/stayapi/agent-skill.git
cp -R agent-skill/skills/stayapi ~/.claude/skills/stayapi

Your API key

The skill needs a StayAPI key to fetch data — the same X-API-Key you use everywhere else. It looks for the key in this order:

  1. A connected StayAPI MCP server — the connector already carries the key, so the agent never touches it.
  2. The STAYAPI_API_KEY environment variable (Claude Code / shell-capable agents).
  3. Failing both, it asks you — and points you to the dashboard if you don't have a key yet.
bash 
export STAYAPI_API_KEY=your_key_here

The skill's instructions explicitly forbid printing, logging, or committing the key — commands always reference the variable, never the literal.

What's inside

skills/stayapi/
├── SKILL.md                  # triggers, auth rules, transport selection, core workflows
└── references/
    ├── workflows.md          # worked examples: destination lookup, search, details,
    │                         # review backfill, Google Hotels, Airbnb
    └── tools.md              # full catalog: 55 MCP tools ↔ REST endpoints, 14 platforms

The skill loads progressively: the agent reads SKILL.md when a hotel-data task appears and opens the reference files only when it needs worked examples or the full platform catalog. It contains documentation only — no code executes, and all data comes from your StayAPI account.

Try it

After installing, ask your agent something like:

  • "Find the top hotels in Lisbon for a weekend in September, with prices."
  • "Get the 20 most recent guest reviews for https://www.booking.com/hotel/us/the-line-la.html"
  • "What do Google reviews say about the Bellagio this month?"

The skill triggers on hotel and travel-data questions automatically. If your agent doesn't pick it up, mention the platform or StayAPI explicitly — "use StayAPI to…" — once, and it will.

Versions & updates

The skill is versioned with tagged releases at stayapi/agent-skill/releases, each with the packaged .skill file attached. To update: Claude Code re-installs from the marketplace; Claude.ai users upload the new release file; manual installs pull the repo again.

Troubleshooting

The skill never triggers.

Confirm it's installed (Claude Code: /plugin → installed plugins; Claude.ai: Settings → Capabilities). Then ask a substantive hotel-data question — one-word prompts may not engage it. Mentioning a platform ("on Booking") or StayAPI by name always helps.

The agent knows what to do but gets no data.

The skill is knowledge, not a connection. On Claude.ai, add the MCP connector. In Claude Code, either add the connector or set STAYAPI_API_KEY so the agent can call the REST API.

401 or 403 on every call.

The key is missing, wrong, or the account is blocked. Check the dashboard for your current key. Quota exhausted returns a structured error with the reset time instead.

Links