Guide · Agent skill
How to use the Google Calendar agent skill (gws-calendar)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-calendar skill is a set of instructions that teaches an AI agent how to work with Google Calendar through the gws command-line tool. Once it is installed and gws is authenticated with your Google account, the agent can look at upcoming events, create events, check free/busy times and manage calendar settings. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to watch out for.
Google Calendar Managergoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws. Install the gws command-line tool (the googleworkspace CLI) on your computer.
- 2Authenticate. Configure Google account authentication for gws, following the gws-shared skill.
- 3Download the skill. Download the gws-calendar ZIP from this page. It contains SKILL.md.
- 4Unzip or upload. Unzip into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 5Ask in plain language. Describe the calendar task you want, including dates, times and the calendar involved.
- 6Review changes. Check the proposed command before confirming any delete, clear or sharing change.
What the gws-calendar skill lets the agent do
A skill is a folder with a SKILL.md file that tells an agent how to handle a specific task. This one covers Google Calendar. The agent reads the file and then runs gws calendar commands on your behalf.
The skill lists two helper commands for everyday use: +insert, which creates a new event, and +agenda, which shows upcoming events across all calendars. Beyond those, it documents the full calendar API resources, including events, calendarList, calendars, acl, freebusy, settings and colors.
- Look at upcoming events across calendars (+agenda)
- Create new events (+insert)
- Check free/busy times with freebusy query
- Manage calendar settings, sharing rules (acl) and secondary calendars
Install the gws-calendar skill
Download the skill ZIP from this page. It contains SKILL.md. Then choose one of the two install routes below.
For Claude Code, unzip the folder into ~/.claude/skills/ to make it available for all your projects, or into a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Set up the gws tool and authentication first
The skill cannot work alone. It requires the gws command-line tool (the googleworkspace CLI) and Google account authentication configured for gws. The skill points to the gws-shared skill for authentication, global flags and security rules. If that file is missing, the source says to run gws generate-skills to create it.
The skill metadata lists gws as a required binary, and the cliHelp entry is gws calendar --help.
- Install the gws command-line tool
- Authenticate gws with your Google account (see the gws-shared skill)
- If gws-shared/SKILL.md is missing, run gws generate-skills
gws calendar --helpAsk for calendar tasks in plain language
You do not need to type commands yourself. Describe the outcome you want and the agent chooses the right helper or API method. Before it acts, the skill tells the agent to inspect the method's required parameters with gws schema, so it builds valid --params and --json flags.
Be specific about dates, times, time zones and which calendar you mean. The more precise the request, the fewer clarifying questions the agent needs to ask.
- "What is on my calendar tomorrow?" (uses +agenda)
- "Create a 30-minute review with Sam on Thursday at 2pm." (uses +insert)
- "When am I free next Tuesday afternoon?" (uses freebusy query)
- "List the sharing rules on my work calendar." (uses acl list)
gws schema calendar.<resource>.<method>Safety: delete and clear operations and service accounts
The skill exposes destructive methods. calendars.clear deletes all events on a primary calendar of an account, and calendars.delete removes a secondary calendar. Events can also be deleted. If the agent acts on a wrong instruction, data can be lost in ways that cannot be undone. Review any delete or clear request before you confirm it.
The skill also runs scripts and uses the network. Its source warns against using a service account for authentication: the service account becomes the data owner of created calendars, which can lead to unexpected behaviour. Authenticate as the intended data owner instead. The source mentions domain-wide delegation as a way to act on behalf of a specific user.
- Review every delete, clear and remove request before confirming
- Avoid service-account-only authentication
- The skill runs scripts and uses the network
Tips for reliable results
Run gws calendar --help to see the resources and methods available. When you want to know exactly what a method needs, run gws schema with the method name. Keep your requests concrete, and check the agent's proposed command before a destructive action runs.
- Use gws calendar --help to browse resources
- Use gws schema calendar.<resource>.<method> to see required parameters
- Ask the agent to show the command before it changes anything
gws schema calendar.<resource>.<method>What people use it for
- Check tomorrow's agenda across all your calendars before a morning meeting.
- Create a new event from a chat request with date, time and attendees.
- Find a free slot for a meeting by checking free/busy times.
- Review or update sharing rules on a work calendar as an admin.
- Create a secondary calendar for a project, once authentication is set up correctly.
Frequently asked questions
How do I install the gws-calendar agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
What do I need before the gws-calendar skill works?
You need the gws command-line tool and Google account authentication configured for gws. The skill cannot work on its own. The gws-shared skill covers authentication, and if it is missing you can run gws generate-skills.
Is the gws-calendar skill free?
The skill is licensed under Apache-2.0, as listed on this page. This page does not state pricing for gws or Google Calendar, so check those separately.
Can the agent delete my calendar events?
The skill exposes delete and clear methods. calendars.clear deletes all events on a primary calendar, which can cause irreversible data loss if the agent acts on a wrong instruction. Review any destructive request before confirming it.
Why does the skill warn about service accounts?
The source says a service account becomes the data owner of calendars it creates, which can lead to unexpected behaviour. It recommends authenticating as the intended data owner, and mentions domain-wide delegation to act on behalf of a specific user.
How is this different from using the gws command directly?
The skill gives the agent the instructions and command reference so it can choose the right gws calendar method from a plain-language request. You can still run the same gws commands yourself; use gws calendar --help and gws schema to explore them.
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
Use this skill if you want an AI agent to read, create or manage Google Calendar entries through the gws tool, or if you are an admin managing calendar access. Skip it if you have not set up gws and Google authentication, or if you want an assistant that cannot delete data, since it exposes destructive methods. Authenticate as the real calendar owner rather than with a service account.
Download the skill