feat: add gws skill for Google Workspace CLI#103
Conversation
Adds a new `gws` skill that wraps the `@googleworkspace/cli` tool for structured, API-based access to Google Calendar, Gmail, Drive, Sheets, Docs, Tasks, and cross-service workflows. Unlike the existing browser-based `google-workspace` skill, this uses direct API calls via the `gws` CLI — faster, more reliable, no bot detection issues, and works headlessly in containers. Key behaviors: - Proactive: runs commands immediately without asking clarifying questions - Auto-install: installs gws via npm if not present - Auth guidance: detects auth errors and guides user through `gws auth login` - Covers helper commands (+agenda, +triage, +send, +read) and raw API access - Confirms before write operations (send email, create events) Tested against live gateway — skill triggers correctly and executes `gws calendar +agenda --week` proactively on calendar queries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new bundled skill definition for using the Google Workspace CLI (gws) as an alternative to browser-based Google Workspace automation, aiming to provide structured, headless access to Workspace APIs.
Changes:
- Introduces
skills/gws/SKILL.mdwith frontmatter metadata (tags, related skills, npm install spec) and detailed usage guidance. - Documents proactive defaults, helper command patterns (
+agenda,+triage,+send), and an “escape hatch” for raw Discovery API calls.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
skills/gws/SKILL.md
Outdated
| Before running any `gws` command, verify the CLI is available: | ||
|
|
||
| ```bash | ||
| which gws || npm install -g @googleworkspace/cli | ||
| ``` |
There was a problem hiding this comment.
The install check recommends npm install -g @googleworkspace/cli directly. This repo already has hybridclaw skill install <skill> [install-id] which uses the skill’s metadata.hybridclaw.install specs (and applies the repo’s npm install flags). To keep setup consistent and safer, prefer documenting hybridclaw skill install gws (or hybridclaw skill install gws npm-1) as the primary path, with manual npm install -g as a fallback.
| - google-workspace | ||
| - himalaya | ||
| install: | ||
| - kind: npm |
There was a problem hiding this comment.
metadata.hybridclaw.install entries typically include a stable id and a human-friendly label (see e.g. skills/1password/SKILL.md). Without these, hybridclaw skill list/install prompts will show an auto-generated id (like npm-1) and an empty label. Consider adding id: npm (or similar) and a label such as "Install Google Workspace CLI (npm)" for consistency.
| - kind: npm | |
| - id: npm | |
| label: Install Google Workspace CLI (npm) | |
| kind: npm |
skills/gws/SKILL.md
Outdated
|
|
||
| ```bash | ||
| gws calendar --help # list resources | ||
| gws schema calendar.events.list # inspect parameters for a method |
There was a problem hiding this comment.
The doc defines the raw syntax as gws <service> <resource> <method> ..., but the discovery example uses dot-notation (gws schema calendar.events.list). This is internally inconsistent and may confuse users/agents about the expected format. Align the schema/discovery example with the documented syntax (or explicitly explain that schema accepts a service.resource.method string if that’s intentional).
| gws schema calendar.events.list # inspect parameters for a method | |
| gws schema calendar events list # inspect parameters for a method |
…preflight Rewrites the gws skill based on official skill authoring best practices: - SKILL.md trimmed from 274 to 90 lines (67% reduction in trigger-time tokens) - Hub-and-spoke pattern: per-service reference files loaded on demand (calendar.md, gmail.md, drive-docs-sheets.md, workflows.md) - Pre-flight auth via `gws auth status` instead of try-and-fail pattern - Single auth path: just "run gws auth login" — no multi-option walls - Smart confirmation: only confirm actions affecting others, not personal time blocks or reminders - Third-person description per official naming guidelines - Renamed to `using-gws` (gerund form per conventions) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The default `gws auth login` uses 7 safe scopes that work for both personal Gmail and Workspace accounts without hitting the unverified app scope limit. No need to mention `gws auth setup` or scope flags. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
maxnoller
force-pushed
the
main
branch
2 times, most recently
from
58c9d19 to
7bf3030
Compare
Summary
gwsskill that wraps@googleworkspace/clifor structured API access to Google Workspace (Calendar, Gmail, Drive, Sheets, Docs, Tasks)gwsvia npm and guides users through OAuth setup when needed+agenda,+triage,+send) and raw Discovery API accessMotivation
Testing showed the browser-based
google-workspaceskill is fragile — it hits login walls, triggers bot detection, and requires persistent browser profiles. The OpenClaw ecosystem has standardized on CLI/MCP tools for Google access. ThegwsCLI (22K GitHub stars, March 2026) outputs structured JSON and ships with 100+ agent skills.Relationship to existing skills
This coexists with the
google-workspaceskill.gwsis the preferred path when CLI access is available;google-workspaceremains as a browser fallback.Test results
Tested against live gateway:
gws calendar +agenda --week(proactive behavior confirmed)gws auth login -s calendar,gmail,...)Test plan
npm run buildpassesgws calendar +agenda --weekproactively on calendar queriesgws auth logingws, authenticate, verify end-to-end Calendar/Gmail/Drive workflows🤖 Generated with Claude Code