Skip to content
Get packs

Guide · Agent skill

How to use the Google Calendar Agenda agent skill (gws-calendar-agenda)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gws-calendar-agenda skill lets an AI agent read your upcoming Google Calendar events and summarise them for you: today, tomorrow, this week, or a set number of days ahead, across all your calendars or one named calendar. It works by having the agent run the gws command-line tool, so it is aimed at people who already use gws or are willing to set it up. This guide explains what an agent skill is, how to install this one, how to ask for it in plain language, and what to check for safety before you rely on it.

Google Calendar Agendagoogleworkspace/cli · Apache-2.0

Quick start

  1. 1Install gws and authenticate. Install the gws command-line tool and sign in with your Google account as described in the gws-shared skill.
  2. 2Download the skill ZIP. Get the gws-calendar-agenda ZIP from the skill page on this site.
  3. 3Unzip into the skills folder. Unzip the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
  4. 4Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
  5. 5Ask about your schedule. Make a plain request such as "What's on my calendar today?" and the agent should use the skill.
  6. 6Narrow the request if needed. Ask for a number of days, a named calendar, or a timezone to get a more specific agenda.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. When a request matches the skill, the agent reads its instructions and carries out the task, here by running commands.

This skill teaches the agent to run the gws calendar +agenda command. It shows upcoming events across all your calendars by default. It is read-only: it does not create, change, or delete events.

  • Covers today, tomorrow, this week, or a set number of days ahead
  • Can filter to all calendars or a named calendar
  • Uses your Google account timezone unless you specify another

What you need before installing

The skill cannot run on its own. It needs the gws command-line tool (the googleworkspace CLI) installed, and a Google account authenticated through gws. The auth details are covered in the gws-shared skill, which this skill refers to as a prerequisite.

If the gws-shared skill file is missing, the source says to run gws generate-skills to create it.

  • gws command-line tool installed
  • A Google account authenticated via gws
  • The gws-shared skill present (run gws generate-skills if it is missing)

Install the skill (ZIP download or Claude apps upload)

Download the ZIP from the skill page on this site and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal: ~/.claude/skills/
  • Project only: .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need to type the command yourself. Ask the agent about your schedule in ordinary language, and it should use this skill when the request is about upcoming events. Mentioning a time range or a calendar name helps the agent pick the right options.

If you want to be explicit, you can name the underlying command the skill uses, which is gws calendar +agenda.

  • "What's on my calendar today?"
  • "What do I have tomorrow morning?" (the agent may need to narrow the time itself)
  • "Show my week ahead in table form."
  • "Check my Work calendar for the next 3 days."
gws calendar +agenda --today

Command options and examples

The skill supports these flags: --today, --tomorrow, --week, --days (number of days ahead), --calendar (calendar name or ID), and --timezone (an IANA timezone such as America/Denver). If you do not set a timezone, the Google account timezone is used. Output formatting is available through --format, as in the table example below.

The examples in the source cover the default run, a single day, a formatted week, a named calendar over several days, and a timezone override.

  • --days sets how many days ahead to show
  • --calendar filters to a calendar by name or ID
  • --timezone overrides the account timezone
gws calendar +agenda gws calendar +agenda --today gws calendar +agenda --week --format table gws calendar +agenda --days 3 --calendar 'Work' gws calendar +agenda --today --timezone America/New_York

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its job is to call Google Calendar through gws, so events are fetched from your Google account. The skill itself is read-only, but the gws tool runs with the access granted when you authenticated it.

Review the SKILL.md file and the gws-shared skill before installing, and make sure you trust the gws tool and the source of the skill folder.

  • Runs scripts: yes
  • Uses network: yes
  • Read-only for events: it does not create, change, or delete them
  • Review the gws-shared auth and security rules before use

What people use it for

  • A morning summary of today's meetings before you start work
  • A weekly overview in table form for planning
  • Checking a named work calendar for the next few days
  • Seeing your schedule in another timezone, such as when coordinating with colleagues elsewhere

Frequently asked questions

How do I install the gws-calendar-agenda skill?

Download the ZIP from the skill page on this site and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to run this skill?

You need the gws command-line tool (googleworkspace CLI) installed and a Google account authenticated through gws. The gws-shared skill covers the auth details.

Is the gws-calendar-agenda skill free?

The source does not state pricing or licence terms beyond the project licence, which is Apache-2.0. Check the repository for details.

Can this skill create or cancel meetings?

No. The skill is read-only and only shows upcoming events. For creating, moving, or cancelling meetings, use the broader gws-calendar skill instead.

What timezone does it use?

It uses your Google account timezone by default. You can override it with --timezone and an IANA timezone name such as America/New_York.

What if the skill does not run or cannot find gws?

The skill cannot run without gws installed and authenticated. Confirm gws works on its own, check that the gws-shared skill is present, and run gws generate-skills if it is missing.

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 people who already use the gws CLI and want an agent to summarise their day or week without opening Google Calendar. It is read-only, so it is safe for checking schedules but not for changing them. If you need to create or move meetings, or you do not have a Google account and gws set up, choose the broader gws-calendar skill or another tool instead.

Download the skill