google-workspace
Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via Python. Uses OAuth2 with automatic token refresh. No external binaries needed — runs entirely with Google's Python client libraries in the Hermes venv.
- License 许可
- MIT
- 最近更新
- 2026-06-24
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- google-workspace
- author
- Nous Research
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "Google", "Gmail", "Calendar", "Drive", "Sheets", "Docs", "Contacts", "Email", "OAuth" ], "homepage": "https://github.com/NousResearch/hermes-agent", "related_skills": [ "himalaya" ] } }
- description
- Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via Python. Uses OAuth2 with automatic token refresh. No external binaries needed — runs entirely with Google's Python client libraries in the Hermes venv.
- required_credential_files
- [ { "path": "google_token.json", "description": "Google OAuth2 token (created by setup script)" }, { "path": "google_client_secret.json" }, "domain/skills", "artifact/skill", { "source/skills-hermes description": "Google OAuth2 client credentials (downloaded from Google Cloud Console)" } ]
02 资源文件 3
- 参考文档references/gmail-search-syntax.md2.3 KB
- 脚本scripts/google_api.py17.7 KB
- 脚本scripts/setup.py10.7 KB
03 SKILL.md 正文
Google Workspace
Gmail, Calendar, Drive, Contacts, Sheets, and Docs — all through Python scripts in this skill. No external binaries to install.
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— API wrapper CLI (agent uses this for all operations)
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:
GSETUP="python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py"
Step 0: Check if already set up
$GSETUP --check
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. -
Calendar, Drive, Sheets, Docs (or email + these) → Continue with this skill's OAuth setup below.
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:
- Go to https://console.cloud.google.com/apis/credentials
- Create a project (or use an existing one)
- Click "Enable APIs" and enable: Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API, People API
- Go to Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: "Desktop app" → Create
- Click "Download JSON" and tell me the file path
Once they provide the path:
$GSETUP --client-secret /path/to/client_secret.json
Step 3: Get authorization URL
$GSETUP --auth-url
This prints a URL. Send the URL to the user and tell them:
Open this link in your browser, sign in with your Google account, and authorize access. After authorizing, you'll be redirected to a page that may show an error — that's expected. Copy the ENTIRE URL from your browser's address bar and paste it back to me.
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:
$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED"
Step 5: Verify
$GSETUP --check
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. - To revoke:
$GSETUP --revoke
Usage
All commands go through the API script. Set GAPI as a shorthand:
GAPI="python ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py"
Gmail
# Search (returns JSON array with id, from, subject, date, snippet)
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
# Read full message (returns JSON with body text)
$GAPI gmail get MESSAGE_ID
# Send
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
# Reply (automatically threads and sets In-Reply-To)
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
# Labels
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
Calendar
# List events (defaults to next 7 days)
$GAPI calendar list
$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
# Create event (ISO 8601 with timezone required)
$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
# Delete event
$GAPI calendar delete EVENT_ID
Drive
$GAPI drive search "quarterly report" --max 10
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
Contacts
$GAPI contacts list --max 20
Sheets
# Read
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
# Write
$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
# Append rows
$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
Docs
$GAPI docs get DOC_ID
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
$GSETUP --revoke
? Связи
- [[MOC - Skills]] — Skills library
- [[skills/skills-hermes]] — Category: skills-hermes
04 同仓库更多 Skills
ckm:ui-styling
Create beautiful, accessible user interfaces with shadcn/ui components (built on Radix UI + Tailwind), Tailwind CSS utility-first styling, and canvas-based visual designs. Use when building user interfaces, implementing design systems, creating responsive layouts, adding accessible components (dialogs, dropdowns, forms, tables), customizing themes and colors, implementing dark mode, generating visual designs and posters, or establishing consistent styling patterns across applications.
ckm:design
Comprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG, Gemini 3.1 Pro), social photos (HTML→screenshot, multi-platform). Actions: design logo, create CIP, generate mockups, build slides, design banner, generate icon, create social photos, social media images, brand identity, design system. Platforms: Facebook, Twitter, LinkedIn, YouTube, Instagram, Pinterest, TikTok, Threads, Google Ads.
ckm:design-system
Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables, spacing/typography scales, component specs, strategic slide creation. Use for design tokens, systematic design, brand-compliant presentations.
ckm:banner-design
Design banners for social media, ads, website heroes, creative assets, and print. Multiple art direction options with AI-generated visuals. Actions: design, create, generate banner. Platforms: Facebook, Twitter/X, LinkedIn, YouTube, Instagram, Google Display, website hero, print. Styles: minimalist, gradient, bold typography, photo-based, illustrated, geometric, retro, glassmorphism, 3D, neon, duotone, editorial, collage. Uses ui-ux-pro-max, frontend-design, ai-artist, ai-multimodal skills.
seo
Comprehensive SEO analysis for any website or business type. Performs full site audits, single-page deep analysis, technical SEO checks (crawlability, indexability, Core Web Vitals with INP), schema markup detection/validation/generation, content quality assessment (E-E-A-T framework per Dec 2025 update extending to all competitive queries), image optimization, sitemap analysis, and Generative Engine Optimization (GEO) for AI Overviews, ChatGPT, and Perplexity citations. Analyzes AI crawler accessibility (GPTBot, ClaudeBot, PerplexityBot), llms.txt compliance, brand mention signals, and passage-level citability. Industry detection for SaaS, e-commerce, local business, publishers, agencies. Triggers on: "SEO", "audit", "schema", "Core Web Vitals", "sitemap", "E-E-A-T", "AI Overviews", "GEO", "technical SEO", "content quality", "page speed", "structured data".
seo-technical
Technical SEO audit across 9 categories: crawlability, indexability, security, URL structure, mobile, Core Web Vitals, structured data, JavaScript rendering, and IndexNow protocol. Use when user says "technical SEO", "crawl issues", "robots.txt", "Core Web Vitals", "site speed", or "security headers".