Agents

Connect your AI agent to VillaSlot and manage your villa listings and bookings through conversation. The VillaSlot skill teaches the agent how to use the API: find an available slot, update a villa's rates, create a customer or manage a reservation.

Your agent works with the same organization data as the application. Access is limited by the organization and permissions attached to your API key.

Choose your agent

Install the VillaSlot skill

Run this command in your terminal from the workspace you use with your agent. You need Node.js and npm available to run npx.

npx skills add https://github.com/mikecodeur/skills --skill villaslot

Follow the installer to choose your agent and installation scope. Installing the skill provides instructions; it does not grant access to your VillaSlot account.

Generate an API key

1. Sign in to VillaSlot and open Account → API Keys.
2. Create a key for the organization whose villas the agent should manage.
3. Store the key securely and make it available to the agent as VILLASLOT_API_KEY.
4. Set VILLASLOT_BASE_URL to https://www.villaslot.io.

Keep the key out of source control and public prompts. It is a VillaSlot API key, separate from your Claude or OpenAI account credentials. The agent's runtime must be able to read the variable and make HTTPS requests.

Ask the agent to start by reading the account context:

Use the villaslot skill. Read my VillaSlot organization context and list
my active villas. Tell me which organization and timezone you are using.
Do not change anything yet.

This first read lets you check the organization before asking the agent to make changes.

What your agent can manage

• Villa listings: list villas, create or rename a villa, upload a photo and archive a villa.
• Availability: read opening hours and priced durations, then find free slots.
• Pricing: replace a villa's hourly rate grid and update booking settings.
• Customers: find or create records, correct contact details and import customer batches.
• Bookings: create hourly bookings, confirm them, move them, mark them complete or cancel them.

Owner/admin permissions are required for villa and booking-setting changes. Organization members can manage customers and bookings within their existing permissions.

Keep control of changes

Give the agent the intended villa, dates and operation. For an import, ask it to show unmatched records before writing. For a rate or opening-hour update, ask it to preserve entries you have not asked to remove: these API operations replace the full collection.

You can revoke the API key from your account when the integration is no longer needed. See the API reference for endpoint permissions, limits and error responses.