tommy-yw/runbookhermes/google-workspace
Claude Code and agent skill by tommy-yw/runbookhermes
- community
Checking that the SKILL.md file is still in the repository.
Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses Hermes-managed OAuth2 setup, prefers the Google Workspace CLI (`gws`) when available for broader API coverage, and falls back to the Python client libraries otherwise.
Install
npx vskill@latest install tommy-yw/runbookhermes/google-workspaceSKILL.md
The same SKILL.md was published earlier as tommy-yw/runbookhermes/google-workspace.
Google Workspace
Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When gws is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.
References
references/gmail-search-syntax.md— Gmail search operators (is:unread, from:, newer_than:, etc.)
Scripts
scripts/setup.py— OAuth2 setup (run once to authorize)scripts/google_api.py— compatibility wrapper CLI. It prefersgwsfor operations when available, while preserving Hermes' existing JSON output contract.
First-Time Setup
The setup is fully non-interactive — you drive it step by step so it works on CLI, Telegram, Discord, or any platform.
Define a shorthand first:
Step 0: Check if already set up
If it prints AUTHENTICATED, skip to Usage — setup is already done.
Step 1: Triage — ask the user what they need
Before starting OAuth setup, ask the user TWO questions:
Question 1: "What Google services do you need? Just email, or also Calendar/Drive/Sheets/Docs?"
- Email only → They don't need this skill at all. Use the
himalayaskill
instead — it works with a Gmail App Password (Settings → Security → App Passwords) and takes 2 minutes to set up. No Google Cloud project needed. Load the himalaya skill and follow its setup instructions.
- Email + Calendar → Continue with this skill, but use
--services email,calendar during auth so the consent screen only asks for the scopes they actually need.
- Calendar/Drive/Sheets/Docs only → Continue with this skill and use a
narrower --services set like calendar,drive,sheets,docs.
- Full Workspace access → Continue with this skill and use the default
all service set.
Question 2: "Does your Google account use Advanced Protection (hardware security keys required to sign in)? If you're not sure, you probably don't — it's something you would have explicitly enrolled in."
- No / Not sure → Normal setup. Continue below.
- Yes → Their Workspace admin must add the OAuth client ID to the org's
allowed apps list before Step 4 will work. Let them know upfront.
Step 2: Create OAuth credentials (one-time, ~5 minutes)
Tell the user:
You need a Google Cloud OAuth client. This is a one-time setup:1. Create or select a project:https://console.cloud.google.com/projectselector2/home/dashboard2. Enable the required APIs from the API Library:https://console.cloud.google.com/apis/libraryEnable: Gmail API, Google Calendar API, Google Drive API,Google Sheets API, Google Docs API, People API3. Create the OAuth client here:https://console.cloud.google.com/apis/credentialsCredentials → Create Credentials → OAuth 2.0 Client ID4. Application type: "Desktop app" → Create5. If the app is still in Testing, add the user's Google account as a test user here:https://console.cloud.google.com/auth/audienceAudience → Test users → Add users6. Download the JSON file and tell me the file pathImportant Hermes CLI note: if the file path starts with/, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:The JSON file path is: /home/user/Downloads/client_secret_....json
Once they provide the path:
If they paste the raw client ID / client secret values instead of a file path, write a valid Desktop OAuth JSON file for them yourself, save it somewhere explicit (for example ~/Downloads/hermes-google-client-secret.json), then run --client-secret against that file.
Step 3: Get authorization URL
Use the service set chosen in Step 1. Examples:
This returns JSON with an auth_url field and also saves the exact URL to ~/.hermes/google_oauth_last_url.txt.
Agent rules for this step:
- Extract the
auth_urlfield and send that exact URL to the user as a single line. - Tell the user that the browser will likely fail on
http://localhost:1after approval, and that this is expected. - Tell them to copy the ENTIRE redirected URL from the browser address bar.
- If the user gets
Error 403: access_denied, send them directly tohttps://console.cloud.google.com/auth/audienceto add themselves as a test user.
Step 4: Exchange the code
The user will paste back either a URL like http://localhost:1/?code=4/0A...&scope=... or just the code string. Either works. The --auth-url step stores a temporary pending OAuth session locally so --auth-code can complete the PKCE exchange later, even on headless systems:
If --auth-code fails because the code expired, was already used, or came from an older browser tab, it now returns a fresh fresh_auth_url. In that case, immediately send the new URL to the user and have them retry with the newest browser redirect only.
Step 5: Verify
Should print AUTHENTICATED. Setup is complete — token refreshes automatically from now on.
Notes
- Token is stored at
~/.hermes/google_token.jsonand auto-refreshes. - Pending OAuth session state/verifier are stored temporarily at
~/.hermes/google_oauth_pending.jsonuntil exchange completes. - If
gwsis installed,google_api.pypoints it at the same~/.hermes/google_token.jsoncredentials file. Users do not need to run a separategws auth loginflow. - To revoke:
$GSETUP --revoke
Usage
All commands go through the API script. Set GAPI as a shorthand:
Gmail
Calendar
Drive
Contacts
Sheets
Docs
Output Format
All commands return JSON. Parse with jq or read directly. Key fields:
- Gmail search:
[{id, threadId, from, to, subject, date, snippet, labels}] - Gmail get:
{id, threadId, from, to, subject, date, labels, body} - Gmail send/reply:
{status: "sent", id, threadId} - Calendar list:
[{id, summary, start, end, location, description, htmlLink}] - Calendar create:
{status: "created", id, summary, htmlLink} - Drive search:
[{id, name, mimeType, modifiedTime, webViewLink}] - Contacts list:
[{name, emails: [...], phones: [...]}] - Sheets get:
[[cell, cell, ...], ...]
Rules
- Never send email or create/delete events without confirming with the user first. Show the draft content and ask for approval.
- Check auth before first use — run
setup.py --check. If it fails, guide the user through setup. - Use the Gmail search syntax reference for complex queries — load it with
skill_view("google-workspace", file_path="references/gmail-search-syntax.md"). - Calendar times must include timezone — always use ISO 8601 with offset (e.g.,
2026-03-01T10:00:00-06:00) or UTC (Z). - Respect rate limits — avoid rapid-fire sequential API calls. Batch reads when possible.
Troubleshooting
| Problem | Fix | |
|---|---|---|
NOT_AUTHENTICATED | Run setup Steps 2-5 above | |
REFRESH_FAILED | Token revoked or expired — redo Steps 3-5 | |
HttpError 403: Insufficient Permission | Missing API scope — $GSETUP --revoke then redo Steps 3-5 | |
HttpError 403: Access Not Configured | API not enabled — user needs to enable it in Google Cloud Console | |
ModuleNotFoundError | Run $GSETUP --install-deps | |
| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
Revoking Access
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/productivity/google-workspace/SKILL.md
Popularity
- Repository stars
- 547
- Repository forks
- 41
- 7-day trend score
- 32
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/tommy-yw/runbookhermes/google-workspace)