Google Calendar is one of the best first integrations for an AI agent.
It is concrete. It is useful. People immediately understand why it matters.
It is also where a lot of agents start doing dumb things.
They create duplicate events. They write to the wrong calendar. They move the wrong recurring instance. They mangle time zones. They treat "calendar" like a simple create/read/update/delete surface.
It is not.
Calendar is live operational state. If an agent writes sloppy calendar data, it does not just produce a bad answer. It changes someone's day.
The most important operating rule is simple:
Search before you create.
That one rule forces the agent to slow down, inspect current state, and decide whether it is actually creating something new or touching something that already exists.
This guide gives you the practical rule set and a portable SKILL.md definition you can adapt for your own agent.
What this skill is for
Use this skill when an agent needs to read, create, update, reschedule, or cancel Google Calendar events.
The skill teaches the agent to:
- choose the right calendar scope before acting
- search before creating new events
- avoid duplicate event creation
- use exact event IDs for updates and deletes
- handle time zones and all-day events carefully
- treat recurring events as high-risk mutations
- separate lookup flows from sync flows
- preserve project or task context when scheduling work
This is not a full Google Calendar API reference. It is the operating playbook an agent should load before using the API or a calendar tool surface.
The mental model
Google Calendar is not just a list of appointments.
It is a stateful system with user calendars, shared calendars, recurring series, modified instances, attendee state, conferencing state, focus time, out-of-office events, notifications, and sync state.
That means the agent needs more than insert, update, and delete.
It needs a decision process.
Before a calendar write, the agent should know:
- Which calendar scope am I operating in?
- What exact time window am I talking about?
- Is there already an event that matches this intent?
- Do I have a local mapping or external event ID for it?
- Is this actually an update, not a create?
- Is this a recurring event or a single event?
- Will this notify attendees?
If those answers are fuzzy, the agent should inspect again or ask the user.
The portable skill definition
Copy this into a portable skill directory such as:
.agents/skills/google-calendar/SKILL.md
You can also adapt it for .buildos/skills/google-calendar/SKILL.md, .claude/skills/google-calendar/SKILL.md, or another compatible skill loader.
---
name: google-calendar
description: Use Google Calendar safely from an AI agent. Use when reading, creating, rescheduling, cancelling, or syncing calendar events; choosing calendar scope; preventing duplicate events; handling recurring events; or linking calendar time to projects and tasks.
---
# Google Calendar
Google Calendar is live operational state. Calendar writes should be conservative because bad writes change someone's day.
## When to Use
- Read calendar events in a time window
- Create work blocks, meetings, reminders, or follow-up sessions
- Reschedule or cancel events
- Search for an existing meeting or work block
- Find availability
- Handle recurring events or one-off exceptions
- Diagnose duplicate event or sync risk
- Link calendar time to a task, project, CRM record, or workflow
## Core Rule
Search before create.
Create only after choosing scope, inspecting the relevant time window, and deciding the request is not really an update to an existing event.
## Workflow
1. Choose scope first: primary calendar, shared calendar, project calendar, or explicit calendar ID.
2. Use bounded lookup: search with an explicit time window and timezone.
3. Search for likely matches by title, time overlap, attendees, linked task/project metadata, local mapping, and external event IDs.
4. If a likely event exists, update it, ask, or confirm whether the user wants an additional event.
5. Create only when no reasonable match exists or the user explicitly wants another event.
6. For update/delete, use exact IDs. Prefer local mapping, then external event ID plus calendar ID.
7. Treat recurring events as high risk. Clarify whether the user means one instance, future instances, or the whole series.
8. Report what changed and mention attendee notifications or sync implications when relevant.
## Read Rules
- Use explicit start and end bounds.
- Carry timezone when available.
- Use text search for lookup tasks like "find the design review."
- Use free/busy or availability tools when the user asks for an open slot.
- Return concrete recurring instances when the user asks what is on the calendar.
## Create Rules
- Never create blindly.
- Search the target time window first.
- Prefer adding metadata that links the event to the originating task, project, CRM record, or workflow.
- If confidence is low, ask before creating.
- Do not create a replacement event as a hidden fallback for a failed update.
## Update and Delete Rules
- Use exact event IDs or local mapped IDs.
- Verify calendar scope before mutation.
- Verify whether attendees may be notified.
- For important or complex writes, read the existing event first and merge intended changes.
- Do not mutate based on vague title matching alone.
## Recurrence Rules
- "Only this one" means edit the specific instance.
- "From now on" means edit future instances or the future series shape.
- "All of them" means edit the full series.
- If wording is ambiguous, ask.
- Never silently apply a broad recurrence edit.
## Time Rules
- Prefer timezone-safe ISO 8601 datetimes.
- Treat date-only and all-day events separately from timed events.
- Do not invent a precise time when the user only gave a date.
- If only a start time is known, ask or use the product's explicit default-duration policy.
## Sync Rules
Lookup and sync are different jobs.
- Use list/search for discovery and duplicate prevention.
- Use incremental sync tokens only for "what changed since last time?"
- Do not combine search matching logic with sync-token state.
- If sync state is broken, report or repair it; do not casually recreate events.
## Examples
### Reschedule an existing meeting
User: "Move my design review Thursday from 3 to 4."
1. Choose calendar scope.
2. Search Thursday for "design review."
3. Inspect likely matches.
4. If one obvious match exists, update that event ID.
5. If multiple plausible matches exist, ask.
6. Do not create a second event at 4.
### Create a project work block
User: "Next week, schedule 90 minutes to work on the investor deck."
1. Resolve the project or task if the agent has access to one.
2. Search next week for existing investor-deck or fundraising work blocks.
3. If a work block exists, ask whether to move it or add another session.
4. If none exists, find a slot and create the event.
5. Store task/project metadata when supported.
### Move one recurring instance
User: "Move tomorrow's standup to 11, but only tomorrow."
1. Search the narrow target window.
2. Identify the concrete recurring instance.
3. Update only that instance.
4. Preserve the rest of the series.
Optional BuildOS metadata
If you are maintaining a catalog, keep SKILL.md portable and put marketplace or install metadata in a separate buildos.yaml.
id: google-workspace/google-calendar
version: '1.0.0'
author: buildos
license: MIT
tags:
- google-calendar
- google-workspace
- scheduling
- agent-skills
requires:
tools:
- google_calendar.list_events
- google_calendar.create_event
- google_calendar.update_event
- google_calendar.delete_event
env: []
permissions:
network: true
filesystem: none
shell: false
ui:
display_name: Google Calendar
short_description: Use Google Calendar safely without duplicate events or recurrence mistakes.
default_prompt: Use Google Calendar to inspect, schedule, or reschedule events safely.
Why search before create matters
The classic failure mode is simple.
The user says:
Schedule time next week to work on the investor deck.
The naive agent creates a new event immediately.
But maybe a work block already exists. Maybe the event exists under a slightly different title. Maybe the task is already linked to a project calendar. Maybe the event is part of a recurring planning block.
Now the calendar has duplicates.
The better behavior is:
- choose scope
- search the target week
- inspect likely matches
- decide create vs update vs ask
- only then write
Calendar agents should be biased toward preserving state, not generating state.
Scope is part of correctness
There is a big difference between:
- a user's primary calendar
- a shared team calendar
- a project calendar
- a calendar ID returned by a previous lookup
If the agent writes to the wrong calendar, the API call may succeed while the action is still wrong.
So the skill tells the agent to choose scope first. This one habit prevents a surprising number of downstream mistakes.
Event identity matters
Calendar mutation should use stable identity whenever possible.
The best write path is:
- local mapped event ID
- external Google Calendar event ID plus calendar ID
- strong match from a narrow lookup
- ask the user
The weak write path is:
- guessed title
- guessed date
- mutation
That path is how agents move the wrong meeting.
Recurrence is high risk
Recurring events expose whether an agent actually understands calendar behavior.
"Move tomorrow's standup" is not the same request as "move standup from now on."
The skill definition bakes in the decision rule:
- "only this one" means instance edit
- "from now on" means future-series edit
- "all of them" means full-series edit
If the user does not specify, the agent should ask. It should not silently choose.
Lookup and sync are different
Search answers: what exists right now?
Sync answers: what changed since last time?
Those are not the same flow. A good agent can search a calendar to find the right event to edit. A background integration can sync calendar changes to keep local state current. Mixing those concerns makes systems brittle.
This distinction matters once the agent moves beyond toy examples and starts living inside real workflows.
How BuildOS uses this pattern
BuildOS treats calendar time as part of operating context, not isolated scheduling.
A calendar event can connect to:
- a project
- a task
- a work session
- a deadline
- a daily brief
- a future follow-up
That is why this skill is more than a Google Calendar API wrapper. The useful agent behavior is not "create events faster." It is "place the right work on the calendar without making the calendar worse."
What to build next
This skill stacks naturally with:
- OAuth 2.0 for agents
- Gmail draft and reply handling
- Google Drive and Docs context search
- Founder assistant stack: Gmail + Calendar + BuildOS
- Meeting notes to tasks and documents
Start with Calendar because it is concrete. Expand into Google Workspace once the agent can safely read state, choose scope, and write without duplicating events.
References
- Google Calendar API Events resource: https://developers.google.com/workspace/calendar/api/v3/reference/events
- Google Calendar events.list: https://developers.google.com/workspace/calendar/api/v3/reference/events/list
- Google Calendar events.insert: https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
- Google Calendar events.patch: https://developers.google.com/workspace/calendar/api/v3/reference/events/patch
- Google Calendar recurring events guide: https://developers.google.com/workspace/calendar/api/guides/recurringevents
- Google Calendar extended properties guide: https://developers.google.com/workspace/calendar/api/guides/extended-properties
- Google Calendar push notifications guide: https://developers.google.com/workspace/calendar/api/guides/push
- Google Calendar free/busy query: https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query