Guide · Agent skill
How to use the Find Free Time Across Calendars agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Find Free Time Across Calendars skill, named recipe-find-free-time, lets an AI agent check Google Calendar free/busy status for several people over a time window, find a slot that works for everyone, and create an event for it. It is aimed at team leads, assistants and anyone already using the gws command-line tool with Google Workspace. After this guide you will know what the skill does, how to install it, how to ask for it in plain language and what to check before it books anything.
Find Free Time Across Calendarsgoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws and authenticate. Install the gws command-line tool and sign in with Google Workspace so it can reach Google Calendar.
- 2Load the gws-calendar skill. Make sure the gws-calendar skill is available, since this recipe requires it.
- 3Download and unzip this skill. Download the ZIP from our page and unzip the skill folder.
- 4Place the skill folder. Put it in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Ask in plain language. Name the people, the date, the time window and the meeting length in your request.
- 6Review the free slots. Check the overlapping free times the agent finds before accepting any slot.
- 7Approve the event. Confirm the attendee list and time, since the created event invites real people.
What the skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches them. This skill covers one scheduling task: querying Google Calendar free/busy status for multiple users to find a meeting slot.
The source describes three steps. The agent queries free/busy data for the users over a time window, reviews the output to find overlapping free slots, and then creates an event in a free slot with the attendees added.
What you need before installing
The skill depends on two things. First, the gws command-line tool must be installed and authenticated with Google Workspace. Second, the gws-calendar skill must be loaded, since the recipe lists it as a prerequisite. You also need Google Calendar access to the users you want to query, because free/busy lookups need permission to view those calendars.
The skill itself does not talk to Google Calendar directly. It relies on gws and gws-calendar to do that work.
- gws command-line tool installed and authenticated with Google Workspace
- gws-calendar skill loaded
- Google Calendar access to the users being queried
Install the skill
Download the ZIP for this skill from our page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
How to trigger the skill with natural requests
You do not need a special command. Describe the goal in plain language and name the people and time window. The agent should match the request to this skill when it involves finding free time across several calendars.
Include the people's calendar addresses if you have them, a date and a time range, and the meeting length. The source examples use addresses in the form user@company.com and a 30-minute meeting.
- Find a 30-minute slot on 18 March 2024 between 8am and 6pm UTC for user1@company.com and user2@company.com.
- Check when user1@company.com and user2@company.com are both free next Monday afternoon and book a 30-minute meeting called Project sync.
- Find a time this week when my colleagues are all free for an hour and invite them.
What the agent runs behind the scenes
The source shows the underlying commands the agent uses. A free/busy query takes a time window and a list of calendar IDs. The agent then creates the event with gws calendar +insert, passing the summary, attendees, start and end times.
You can read these examples to understand what will run. The agent is expected to pick a slot from the query output rather than guess one.
gws calendar freebusy query --json '{"timeMin": "2024-03-18T08:00:00Z", "timeMax": "2024-03-18T18:00:00Z", "items": [{"id": "user1@company.com"}, {"id": "user2@company.com"}]}'
gws calendar +insert --summary 'Meeting' --attendee user1@company.com --attendee user2@company.com --start '2024-03-18T14:00:00' --end '2024-03-18T14:30:00'Safety notes: scripts and network access
This skill runs scripts and uses the network. The commands above query and modify Google Calendar through the gws tool, so the agent acts on real accounts with the permissions you have given gws.
The skill does not describe a confirmation step before creating an event. Events created this way invite real attendees. Review the proposed slot and attendee list before you let the agent create the event.
- Check the attendee list before any event is created.
- Only query calendars you are allowed to view.
- Use an account whose calendar access you are comfortable letting the tool use.
Tips for better results
Give exact time zones and windows. The example query uses UTC timestamps, so a request without a zone may be read differently than you expect.
Ask the agent to show you the free slots first and then confirm before booking. Since the skill itself has no confirmation step, this check is your responsibility.
- Use full calendar addresses for each attendee.
- Keep the time window narrow to make overlaps easier to read.
- Confirm the proposed slot before asking for the event to be created.
What people use it for
- Scheduling a 30-minute sync across a small team's calendars in one request.
- Assistants finding a shared free hour for an executive and several colleagues.
- Checking whether a group has any overlapping free time on a given afternoon.
- Creating a calendar event for an agreed slot with all attendees added.
Frequently asked questions
How do I install the recipe-find-free-time skill?
Download the ZIP for this skill from our page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What does the skill require to work?
It requires the gws command-line tool installed and authenticated with Google Workspace, the gws-calendar skill loaded, and Google Calendar access to the users you query. Free/busy lookups need permission to view those calendars.
Is the Find Free Time Across Calendars skill free?
The skill is licensed under Apache-2.0. The source does not describe pricing for gws or Google Workspace, so check those separately.
Will the agent book meetings without asking me?
The skill does not describe a confirmation step. It creates events that invite real attendees, so review the proposed slot and attendee list before the agent books it.
Does the skill work without the gws tool?
No. The skill relies on the gws command-line tool and the gws-calendar skill to communicate with Google Calendar.
What are alternatives to this skill?
The source does not compare this skill with other tools. If you do not use gws with Google Workspace, you would need a different calendar integration; this skill is only described for the gws setup.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits team leads and assistants who already use gws with Google Workspace and want the agent to find shared free time and create events. It is not a good fit if you lack view access to the calendars involved or want bookings made without reviewing the proposed slot, since the skill has no described confirmation step.
Download the skill