Gmail to Vault to Calendar: One Conversation with Claude Code
A surprising amount of computer time is just extract-transform-load with extra steps. Someone emails you an update. You read it, pull out what matters, paste it into your notes, then open the calendar and manually create an event from a date buried three paragraphs deep. Each step is trivial. The sequence is tedious. And if you’re doing it across apps — Gmail in a browser, Obsidian on the desktop, Calendar in yet another window — the friction compounds.
I hit this last week. A family member had taken my dad to an appointment and sent a detailed email to the family — what happened, what was discussed, what was decided, when the follow-up is scheduled. The useful information needed to go two places: my dad’s file in the vault (condensed, with date links), and a calendar event for the follow-up appointment a few months out. In a browser that’s five minutes of tabbing and copying. In Claude Code it was one conversation.
The Tools
Three tools, none of which know about each other:
- Google Workspace CLI (
gws) — a Rust binary that talks to Gmail, Calendar, Drive, and every other Google API. It reads Google’s Discovery Service at runtime, so when Google adds endpoints,gwspicks them up automatically. All output is structured JSON. - Obsidian vault — my dad’s file is a markdown document with date-linked entries going back years.
icalCLI — pushes events to Apple Calendar from the command line. (Covered in the travel planning recipe.)
The missing piece was teaching Claude Code how to call gws. That’s where skills come in.
Installing gws
npm install -g @googleworkspace/cliAuthentication requires a Google Cloud project with OAuth credentials. gws auth setup walks you through it if you have gcloud installed; otherwise you create the OAuth client manually in the Cloud Console and run gws auth login. The setup is a one-time pain — pick your scopes (I chose gmail and calendar), approve in the browser, and credentials get encrypted at rest.
The Skill Problem
The gws repo ships 93 agent skills — one for every API surface, plus recipes for common workflows. You can install them all at once:
npx skills add https://github.com/googleworkspace/cliI didn’t. Ninety-three skills means ninety-three SKILL.md files loaded into Claude’s context window every conversation. Most of them — Google Classroom, Model Armor, Chat spaces, persona templates — I will never use. That’s not free. Context window space is the most expensive resource in an agent conversation, and filling it with instructions for APIs you don’t call crowds out the instructions for things you do.
The alternative: clone the repo, read the skills you need, and build a consolidated version.
git clone --depth 1 https://github.com/googleworkspace/cli.git ~/dev/third-party/gws-cli
ls ~/dev/third-party/gws-cli/skills/I read through the seven skills I actually needed — gws-shared (auth and global flags), gws-gmail and its helpers (+triage, +read, +send, +reply, +forward), and gws-calendar with its helpers (+agenda, +insert). Each one was a standalone SKILL.md with its own frontmatter, prerequisite references, and “See Also” footers. Together they totaled over 400 lines, with significant repetition — every file started with “PREREQUISITE: Read gws-shared” and ended with links back to the parent skill.
I consolidated them into a single ~/.claude/skills/gws/SKILL.md — about 165 lines covering both Gmail and Calendar. The cuts:
- Authentication and installation sections — already done, don’t need instructions every session
- Repeated prerequisite banners — the shared content is inline now
- “See Also” cross-references — everything is in one file
- OpenClaw metadata — that’s for the
npx skillssystem, not Claude
What stayed: the CLI syntax pattern, method flags table, the gws schema discovery command (so Claude can look up unfamiliar methods on its own), shell tips, safety rules, and a compact reference card for each helper command with flags and examples. Plus the raw API resource lists so Claude knows what’s available beyond the helpers.
The Workflow
With the skill loaded, the conversation went like this:
Find the email. gws gmail +triage defaults to unread messages only. The email had already been read, so the first attempt returned nothing. Passing a --query flag searched all mail and surfaced the thread.
gws gmail +triage --max 10 --query 'from:ned'Read it. +read pulls the full message body by ID. I read both messages in the thread to get the complete picture.
gws gmail +read --id 19d02c9883b53082 --headersSummarize and write to the vault. Claude had the email content and already knew where my dad’s file was — not because it searched for it, but because a context file listed family members with wikilinks to their notes. It followed the link, read the existing format (date-linked entries, newest first, bullet points), and added a new entry summarizing the update. More on how that worked below.
Create the calendar event. The follow-up was a few months out. One wrinkle: I’m currently in Spain (CEST) but the appointment is in the US (CDT). The ical CLI’s --timezone flag handled this.
ical add "Grampa Simpson - Follow-up Appointment" \
--start "2026-06-17 14:00" \
--end "2026-06-17 15:00" \
--timezone "America/Chicago" \
--calendar "Family" \
--location "Springfield Medical Center" \
--alert 1dThe event showed up as 9pm on my calendar in Spain — correct conversion from 2pm Central.
How Context Files Made This Seamless
The part that surprised me was how little direction Claude needed to find the right file. I said something like “add this to my dad’s file” and it went straight there — no search, no asking me for the path.
This worked because of the context file system. A context file in my vault lists family members with brief descriptions and wikilinks to their notes. Claude loaded that file, found the link, followed it to my dad’s note, read the existing format, and matched it. The whole chain — identify the person, find their file, understand the structure, add the entry — happened through link-following, not search.
Without that pointer, Claude would have needed a vault search, maybe several, and I’d have needed to confirm the right file. The context layer turned “add this to my dad’s file” from an ambiguous request into an unambiguous lookup.
What I Learned
Skill curation matters more than skill quantity. The instinct with agent tool registries is “install everything, let the agent figure out what to use.” But every skill file competes for attention in the context window. A focused skill that covers your actual use cases beats a comprehensive one that covers everyone’s. The 93-to-1 compression wasn’t just about file count — it was about signal density.
The corollary: test the skill on a real task immediately. We hit two issues on the first use — +triage defaulting to unread (wasting a round trip), and +read not supporting a --format text flag that the upstream skill documented. Both were small fixes. If we’d waited to discover these in a future session, we’d have lost the context of what went wrong.
The ical CLI had a similar gap. Its natural language date parser doesn’t accept timezone abbreviations like “CDT” embedded in the date string — you need --timezone "America/Chicago" with an IANA name. We filed an issue upstream to get it documented. These are the kinds of things you only find by using the tool, and they’re easiest to fix while the failure is fresh.
Caveats
gws is young. The Google Workspace CLI has been around for a few weeks. It’s backed by Google engineers but explicitly “not an officially supported Google product.” The API surface is huge and generated dynamically from Discovery docs — edge cases are likely.
OAuth scope limits. If your Google Cloud app is in testing mode (unverified), you’re limited to ~25 OAuth scopes. The full gws scope set exceeds this. Pick only the services you need: gws auth login -s drive,gmail,calendar.
The consolidated skill is a snapshot. When gws adds new helper commands or flags, the upstream skills will reflect that. My consolidated version won’t. I keep the cloned repo at ~/dev/third-party/gws-cli/ so I can check for updates and pull in changes selectively.
Apple Calendar timezone display. Events created with --timezone store the correct time but display in whatever timezone your Mac is set to. If you’re traveling, the times shift on screen. The underlying time is right — it just looks different depending on where you are.