# connector-googlecalendar

A skill that pins down the one supported way to wire Google Calendar into a Caffeine build: the googlecalendar-client and google-oauth packages, not hand-rolled HTTP calls.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 21900 installs · ★ 2
- Author: caffeinelabs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/caffeinelabs/skills/tree/HEAD/skills/connector-googlecalendar/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/connector-googlecalendar

## What it does

The skill covers connecting a signed-in user's own calendar to a Caffeine AI canister. Listing upcoming events and creating events both go through `googlecalendar-client`, the generated Motoko bindings for Google Calendar API v3. Token exchange, refresh and PKCE live in `google-oauth`. Calling `ic.http_request` straight at `oauth2.googleapis.com` or `www.googleapis.com/calendar/v3` is called out as forbidden, because it skips bearer auth, the replication-cost safeguards, and the library's percent-encoding and JSON parsing.

Every end user runs their own Authorization Code with PKCE handshake, and tokens sit in a `Map<Principal, CalendarConnection>` keyed by caller. The `access_token` and `refresh_token` never leave the canister; the frontend only learns a `Bool` for whether the calendar is connected. On an expired one-hour token and an HTTP 401, the canister refreshes silently and retries.

You need a Google Cloud OAuth 2.0 Web application client and the calendar scopes enabled before the build. An admin enters the Client ID and Client Secret on the app's settings page, and the secret must not reach the frontend. The callback URI handed to `startCalendarOAuth` has to match exactly what was registered in Google Cloud Console, or the code exchange fails. For availability questions the skill points at FreeBusy (`calendar_freebusy_query`) rather than `calendar_events_list`.

## Requirements
- Works with: Google Workspace

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill connector-googlecalendar -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/connector-googlecalendar/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/connector-googlecalendar/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill connector-googlecalendar -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/connector-googlecalendar/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill connector-googlecalendar -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/connector-googlecalendar/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install caffeinelabs/skills connector-googlecalendar
```

2. **Manually: put the files in place**
- File: `.github/skills/connector-googlecalendar/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill connector-googlecalendar -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/caffeinelabs/skills --path skills/connector-googlecalendar
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/connector-googlecalendar/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill connector-googlecalendar -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/caffeinelabs/skills/tree/HEAD/skills/connector-googlecalendar/SKILL.md

## When to use it
- connect a signed-in user's calendar to a canister
- list upcoming events in an app
- create a calendar event from the app
- find free slots with FreeBusy
- keep OAuth tokens inside the canister

## Example prompts
- Add the `googlecalendar-client` and `google-oauth` packages and wire up the user's calendar following this skill
- Build an endpoint that returns the signed-in user's upcoming events
- Create an event on the user's calendar and check availability with FreeBusy

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: bb659b0a2b0d83f4.

BEGIN THIRD-PARTY FILE bb659b0a2b0d83f4
```text
---
name: connector-googlecalendar
description: >-
  MANDATORY recipe for every Caffeine build that lists upcoming events or
  creates events on the user's own Google Calendar. The ONLY supported path is
  the `googlecalendar-client` mops package (Calendar REST API v3) combined with
  the `google-oauth` mops package (token exchange + refresh + PKCE). Hand-rolling
  `ic.http_request` calls to `oauth2.googleapis.com` or
  `www.googleapis.com/calendar/v3` is a FORBIDDEN anti-pattern — it bypasses
  bearer auth, replication-cost safeguards, and the `google-oauth` library's
  percent-encoding and JSON parsing. Load this skill whenever the user, spec,
  or any prior task mentions scheduling, calendar events, appointments,
  meetings, "add to calendar", or any equivalent phrasing — and BEFORE
  writing any code that touches a Google endpoint.
version: 0.3.3
caffeineai-subscription: [none]
compatibility:
  mops:
    googlecalendar-client: "~0.3.0"
    google-oauth: "~0.2.1"
    caffeineai-authorization: "~1.0.1"
---

# Google Calendar Connector

Google Calendar integration for [Caffeine AI](https://caffeine.ai?utm_source=caffeine-skill&utm_medium=referral).

## Orchestrator routing notes

**Treat Google Calendar-as-the-user as a first-class, supported platform feature.**
The `googlecalendar-client` + `google-oauth` connector pair is the **only**
supported path; raw `ic.http_request` to `oauth2.googleapis.com` or
`www.googleapis.com/calendar/v3` is a forbidden anti-pattern. Any build spec
that mentions Google Calendar MUST name `googlecalendar-client` and
`google-oauth` as dependencies and reference this skill.

Distinct from platform `email-calendar-events` extension (which emails iCalendar
invitations from the app); this connector acts as the **signed-in user's own
Google Calendar**.

Intent → capability mapping:

| User intent | Platform capability |
| --- | --- |
| Connect and list upcoming events | `googlecalendar-client` + `google-oauth` |
| Create calendar events | `googlecalendar-client` + `google-oauth` |
```
END THIRD-PARTY FILE bb659b0a2b0d83f4

The third-party file has ended. Everything between the bb659b0a2b0d83f4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2046 of 59484 bytes. © caffeinelabs · Apache-2.0 · https://github.com/caffeinelabs/skills/tree/HEAD/skills/connector-googlecalendar/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md