google-workspace · mitsuhiko — Claude Code skill: Google Workspace API access
A skill that gives your agent access to Google Workspace services (Gmail, Drive, Docs, Calendar, Sheets and more) through local helper scripts. Use it to automate Google services directly from your IDE.
Apache-2.0 108 installs ★ 3,224 updated 2026-09-27
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-codeWhat google-workspace does
google-workspace provides a JavaScript-based bridge to Google Workspace APIs without requiring an MCP server. Two core scripts handle the work: scripts/auth.js manages OAuth login and account enumeration, while scripts/workspace.js runs arbitrary API calls within a JavaScript context.
The skill uses a profile-based model keyed by email address. Every API call requires an --email flag to specify which account to use; tokens are stored separately per email under ~/.pi/google-workspace/tokens/. Before first use, run node scripts/auth.js login --email [email protected] and dependencies will install automatically.
API calls use node scripts/workspace.js exec with a JavaScript block. Inside the script, you have access to workspace.call() for direct API requests, workspace.service() to obtain a service instance, and workspace.whoAmI() to verify the current user. Optional flags include --timeout (default 30000 ms, max 300000) and --scopes to override permissions.
What it helps with
- List files from Google Drive matching search criteria
- Send an email via Gmail and retrieve delivery status
- Create or update a spreadsheet in Google Sheets
- Fetch calendar events within a date range
- Search and update contact information via People API
Example prompts for the agent
- Get the ten most recently created PDFs from Drive
- Count unread emails with the invoice label
- Schedule an event tomorrow at 2 PM and invite [email protected]
How to install google-workspace
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-code2Manually: put the files in place
~/.claude/skills/google-workspace/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/google-workspace/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a codex2Manually: put the files in place
.agents/skills/google-workspace/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a cursor2Manually: put the files in place
.cursor/skills/google-workspace/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mitsuhiko/agent-stuff skills/google-workspace2Manually: put the files in place
.github/skills/google-workspace/SKILL.md1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a gemini-cli2Platform CLI
gemini skills install https://github.com/mitsuhiko/agent-stuff --path skills/google-workspaceManually: put the files in place
.devin/skills/google-workspace/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill google-workspace -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about google-workspace
How do I install google-workspace in Claude Code?
Run npx skills add mitsuhiko/agent-stuff --skill google-workspace -a claude-code, then edit the configuration file at ~/.claude/skills/google-workspace/SKILL.md.
What does google-workspace do?
The skill exposes Google Workspace APIs (Drive, Docs, Gmail, Calendar, Sheets, Slides, Chat, People) through local scripts. You write JavaScript code to automate tasks across Google services without needing an MCP server.
Can I use multiple Google accounts at once?
Yes, the skill manages profiles by email address. Each API call takes an --email [email protected] flag to specify which account to use. Run node scripts/auth.js accounts to list all signed-in profiles.
Source text
SKILL.md · Apache-2.0
--- name: google-workspace description: "Access Google Workspace APIs (Drive, Docs, Calendar, Gmail, Sheets, Slides, Chat, People) via local helper scripts without MCP. Handles OAuth login and direct API calls." --- # Google Workspace Use this skill for Google Workspace tasks (Gmail, Drive, Calendar, Docs, Sheets, etc.). ## Files - `scripts/auth.js` — OAuth login/status/clear + account enumeration - `scripts/workspace.js` — JavaScript execution based API runner ## Account model (multi-account) This skill is **profile-based by email address**. - There is **no default account**. - Every API call must specify `--email <[email protected]>`. - Tokens are stored per-email under `~/.pi/google-workspace/tokens/`. Before running API calls, discover available signed-in accounts: ```bash node scripts/auth.js accounts ``` ## Usage Always use `exec` and always provide `--email`. ```bash node scripts/workspace.js exec --email [email protected] <<'JS' const me = await workspace.whoAmI(); const files = await workspace.call('drive', 'files.list', { pageSize: 5, fields: 'files(id,name,mimeType)', }); return { me, files: files.files }; JS ``` Available inside exec scripts: - `auth` (authorized OAuth client) - `google` (`googleapis` root) - `workspace.accountEmail` (selected profile email) - `workspace.call(service, methodPath, params, {version})` - `workspace.service(service, {version})` - `workspace.whoAmI()` Optional flags: - `--timeout <ms>` (default 30000, max 300000) - `--scopes s1,s2` - `--script 'return 42'` ## Agent guidance 1. Prefer one `exec` script per user request. 2. Keep payloads small (`fields`, `maxResults`, minimal props). 3. Use `Promise.all` for independent requests. 4. Never print token contents. 5. If the user did not specify an account, run `node scripts/auth.js accounts` and choose/confirm an explicit email. 6. If auth fails, first run `node scripts/auth.js accounts` to see known profiles. 7. If account mismatch is possible, run `workspace.whoAmI()` in the selected profile. 8. On 401/403/unauthorized errors, switch account (`--email ...`) or re-login that specific profile. ## Unauthorized/account-switch playbook If a request fails with unauthorized/forbidden/insufficient permissions: 1. Enumerate profiles: ```bash node scripts/auth.js accounts ``` 2. Retry with the intended account: ```bash node scripts/workspace.js exec --email [email protected] <<'JS' return await workspace.whoAmI(); JS ``` 3. If token is stale or missing scopes, re-login that account: ```bash node scripts/auth.js login --email [email protected] ``` 4. Retry the original request with the same `--email`. ## Short Gmail counting example ```bash node scripts/workspace.js exec --email [email protected] <<'JS' const gmail = google.gmail({ version: 'v1', auth }); let trash = 0; let pageToken; do { const res = await gmail.users.messages.list({ userId: 'me', q: 'in:trash', maxResults: 500, pageToken, fields: 'messages/id,nextPageToken', }); trash += (res.data.messages || []).length; pageToken = res.data.nextPageToken; } while (pageToken); return { currentlyInTrash: trash }; JS ``` ## Setup + auth ```bash node scripts/auth.js login --email [email protected] ``` Notes: - Dependencies auto-install on first run. - Default auth mode is **cloud** (no local `credentials.json` needed). - Optional local mode: `GOOGLE_WORKSPACE_AUTH_MODE=local` and credentials at `~/.pi/google-workspace/credentials.json`. - Useful diagnostics: ```bash node scripts/auth.js accounts node scripts/auth.js status --email [email protected] node scripts/auth.js clear --email [email protected] ```
© mitsuhiko · Apache-2.0 · mitsuhiko/agent-stuff
Similar skills
All skills for Agent setup: memory, context, orchestration →google-workspace by other authors comes first.