From 4cec100078b2f92326622303420bd29f6f822483 Mon Sep 17 00:00:00 2001 From: Maximilian Noller Date: Sun, 22 Mar 2026 14:15:52 +0100 Subject: [PATCH 1/3] feat: add gws skill for Google Workspace CLI integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- skills/gws/SKILL.md | 274 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 skills/gws/SKILL.md diff --git a/skills/gws/SKILL.md b/skills/gws/SKILL.md new file mode 100644 index 00000000..d5b2ef84 --- /dev/null +++ b/skills/gws/SKILL.md @@ -0,0 +1,274 @@ +--- +name: gws +description: >- + Use the Google Workspace CLI (`gws`) for Calendar, Gmail, Drive, Sheets, Docs, + and Tasks. Trigger this skill whenever the user mentions anything related to + their Google account: checking calendar, sending email, finding files in Drive, + reading or editing spreadsheets, creating documents, managing tasks, or any + cross-service workflow like "prep for my next meeting" or "what's on my plate + today". Also trigger when the user says "gws", "google workspace", or asks + about meetings, events, inbox, unread mail, shared docs, or spreadsheets — + even if they don't explicitly mention Google. +user-invocable: true +metadata: + hybridclaw: + tags: + - google + - workspace + - calendar + - gmail + - drive + - sheets + - docs + - tasks + related_skills: + - google-workspace + - himalaya + install: + - kind: npm + package: "@googleworkspace/cli" + bins: + - gws +--- + +# Google Workspace CLI + +This skill uses `gws` — a CLI that talks directly to every Google Workspace API. +It outputs structured JSON, handles auth, and covers Calendar, Gmail, Drive, +Sheets, Docs, Chat, Tasks, Meet, and more. + +The reason this is better than browser automation for Google Workspace is that +`gws` gives you structured data, runs in milliseconds, never hits CAPTCHAs or +bot detection, and works headlessly in containers. Browser automation should only +be a last resort for Google services. + +## First: check that gws is installed and authenticated + +Before running any `gws` command, verify the CLI is available: + +```bash +which gws || npm install -g @googleworkspace/cli +``` + +Then check auth status by running a lightweight command: + +```bash +gws calendar +agenda --today 2>&1 +``` + +If this returns an auth error (exit code 2), tell the user: + +> You need to authenticate with Google first. Run this in your terminal: +> +> ``` +> gws auth login -s calendar,gmail,drive,sheets,docs,tasks +> ``` +> +> This opens a browser for Google OAuth. After you sign in, try your request +> again. + +If `gws auth login` itself fails because no OAuth client is configured, guide +the user through `gws auth setup` which creates a Cloud project automatically +(requires `gcloud` CLI), or point them to the manual setup in the gws README. + +Do not attempt to run `gws auth login` yourself — it requires an interactive +browser session. Just tell the user what to run. + +## Be proactive + +When the user asks about their calendar, email, files, or tasks — act +immediately. Run the appropriate `gws` command without asking clarifying +questions first. Use sensible defaults: + +- Calendar: default to `primary` calendar, current timezone, this week +- Gmail: default to `userId: me`, unread inbox +- Drive: default to listing recent files +- Sheets: if they mention a spreadsheet name, search Drive for it first + +Only ask for clarification when genuinely ambiguous — like "which spreadsheet?" +when there are multiple matches, or when creating events that need specific +attendees. + +## Helper commands (use these first) + +The `+` prefixed commands are concise shortcuts that handle the common cases. +Prefer these over raw API commands. + +### Calendar + +```bash +# Today's agenda +gws calendar +agenda --today + +# Tomorrow +gws calendar +agenda --tomorrow + +# This week +gws calendar +agenda --week + +# Next N days +gws calendar +agenda --days 7 + +# Specific calendar +gws calendar +agenda --week --calendar "Work" + +# Create an event (always confirm with the user first) +gws calendar +insert \ + --summary "Team standup" \ + --start "2026-03-25T10:00:00" \ + --end "2026-03-25T10:30:00" \ + --location "Room 3A" \ + --description "Weekly sync" \ + --attendee alice@example.com \ + --attendee bob@example.com \ + --meet # adds a Google Meet link + +# Quick add (natural language) +gws calendar events quickAdd \ + --params '{"calendarId": "primary", "text": "Lunch with Alice tomorrow at noon"}' +``` + +### Gmail + +```bash +# Unread inbox summary +gws gmail +triage + +# Triage with limit +gws gmail +triage --max 5 + +# Search +gws gmail +triage --query "from:boss subject:urgent" + +# Read a specific message +gws gmail +read --id MESSAGE_ID + +# Send email (always confirm with user first) +gws gmail +send \ + --to recipient@example.com \ + --subject "Meeting notes" \ + --body "Here are the notes from today's meeting..." \ + --attach ./notes.pdf + +# Reply +gws gmail +reply --message-id MSG_ID --body "Thanks, sounds good." + +# Forward +gws gmail +forward --message-id MSG_ID --to someone@example.com +``` + +### Drive + +```bash +# Upload a file +gws drive +upload ./report.pdf --name "Q1 Report" --parent FOLDER_ID + +# List recent files +gws drive files list --params '{"pageSize": 10}' + +# Search for files +gws drive files list --params '{"q": "name contains '\''budget'\''", "pageSize": 10}' + +# Download a file +gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o ./file.pdf +``` + +### Sheets + +```bash +# Read a range +gws sheets +read --spreadsheet "SPREADSHEET_ID" --range "Sheet1!A1:D10" + +# Append rows +gws sheets +append \ + --spreadsheet "SPREADSHEET_ID" \ + --json-values '[["Name", "Score"], ["Alice", 95]]' +``` + +### Docs + +```bash +# Append text to a document +gws docs +write --document "DOC_ID" --text "New section content here" + +# Read a document +gws docs documents get --params '{"documentId": "DOC_ID"}' +``` + +### Workflows (cross-service) + +```bash +# Morning briefing: today's meetings + open tasks +gws workflow +standup-report + +# Prep for your next meeting: agenda, attendees, linked docs +gws workflow +meeting-prep + +# Weekly overview: meetings + unread counts +gws workflow +weekly-digest +``` + +## Raw API commands (escape hatch) + +When helpers don't cover your use case, use the raw Discovery API syntax: + +``` +gws --params '{"key": "value"}' --json '{"body": "data"}' +``` + +All output is JSON by default. Use `--format table` for human-readable output. + +To discover what's available: + +```bash +gws calendar --help # list resources +gws schema calendar.events.list # inspect parameters for a method +``` + +### Useful raw examples + +```bash +# Free/busy query +gws calendar freebusy query \ + --json '{"timeMin": "2026-03-25T00:00:00Z", "timeMax": "2026-03-26T00:00:00Z", "items": [{"id": "primary"}]}' + +# List all calendars +gws calendar calendarList list + +# Get Gmail labels +gws gmail users labels list --params '{"userId": "me"}' + +# Create a spreadsheet +gws sheets spreadsheets create --json '{"properties": {"title": "Budget Tracker"}}' + +# Create a folder in Drive +gws drive files create --json '{"name": "Project Files", "mimeType": "application/vnd.google-apps.folder"}' + +# Export a Google Doc as PDF +gws drive files export --params '{"fileId": "DOC_ID", "mimeType": "application/pdf"}' -o ./doc.pdf +``` + +## Presenting results + +Format `gws` JSON output into clean, readable summaries for the user: + +- **Calendar events**: group by day, show time + title + location. Flag conflicts. +- **Email triage**: show sender, subject, snippet. Highlight urgent items. +- **Drive files**: show name, type, modified date, sharing status. +- **Sheets data**: render as a Markdown table. + +Do not dump raw JSON at the user unless they specifically ask for it. + +## Rules + +- Never send email or create calendar events without explicit user confirmation. + Draft the content first and show it to the user for approval. +- If a command fails with exit code 2 (auth error), guide the user through + `gws auth login` with the appropriate scopes. +- If a command fails with exit code 1 (API error), read the error message and + adjust — common issues are wrong calendar ID, missing permissions, or quota + limits. +- Use `--format json` (the default) for programmatic processing, `--format table` + only when the user wants raw CLI output. +- For shell escaping: wrap JSON in single quotes, use double quotes around + ranges containing `!` (like `"Sheet1!A1:D10"`). From 4ad951f75092d7145ae57b4e84a15be3635ed892 Mon Sep 17 00:00:00 2001 From: Maximilian Noller Date: Sun, 22 Mar 2026 17:37:41 +0100 Subject: [PATCH 2/3] refactor: restructure gws skill with progressive disclosure and auth preflight MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- skills/gws/SKILL.md | 276 ++++----------------- skills/gws/references/calendar.md | 41 +++ skills/gws/references/drive-docs-sheets.md | 57 +++++ skills/gws/references/gmail.md | 37 +++ skills/gws/references/workflows.md | 39 +++ 5 files changed, 220 insertions(+), 230 deletions(-) create mode 100644 skills/gws/references/calendar.md create mode 100644 skills/gws/references/drive-docs-sheets.md create mode 100644 skills/gws/references/gmail.md create mode 100644 skills/gws/references/workflows.md diff --git a/skills/gws/SKILL.md b/skills/gws/SKILL.md index d5b2ef84..269c5d0d 100644 --- a/skills/gws/SKILL.md +++ b/skills/gws/SKILL.md @@ -1,14 +1,13 @@ --- -name: gws +name: using-gws description: >- - Use the Google Workspace CLI (`gws`) for Calendar, Gmail, Drive, Sheets, Docs, - and Tasks. Trigger this skill whenever the user mentions anything related to - their Google account: checking calendar, sending email, finding files in Drive, - reading or editing spreadsheets, creating documents, managing tasks, or any - cross-service workflow like "prep for my next meeting" or "what's on my plate - today". Also trigger when the user says "gws", "google workspace", or asks - about meetings, events, inbox, unread mail, shared docs, or spreadsheets — - even if they don't explicitly mention Google. + Interacts with Google Workspace via the gws CLI for Calendar, Gmail, Drive, + Sheets, and Docs. Checks calendars, triages email, searches Drive, reads + spreadsheets, and runs cross-service workflows like morning briefings and + meeting prep. Triggers on any mention of calendar, meetings, schedule, email, + inbox, unread mail, Google Drive, spreadsheets, documents, tasks, or requests + like "what's my day look like" and "morning briefing" — even without + explicitly mentioning Google. user-invocable: true metadata: hybridclaw: @@ -23,7 +22,6 @@ metadata: - tasks related_skills: - google-workspace - - himalaya install: - kind: npm package: "@googleworkspace/cli" @@ -31,244 +29,62 @@ metadata: - gws --- -# Google Workspace CLI +# Google Workspace via gws CLI -This skill uses `gws` — a CLI that talks directly to every Google Workspace API. -It outputs structured JSON, handles auth, and covers Calendar, Gmail, Drive, -Sheets, Docs, Chat, Tasks, Meet, and more. +## Step 1: Check auth before anything else -The reason this is better than browser automation for Google Workspace is that -`gws` gives you structured data, runs in milliseconds, never hits CAPTCHAs or -bot detection, and works headlessly in containers. Browser automation should only -be a last resort for Google services. +Run `gws auth status` (no API call, instant) and parse the JSON output. +If `auth_method` is `"none"`, tell the user: -## First: check that gws is installed and authenticated +> Run `gws auth login` in your terminal to connect your Google account. -Before running any `gws` command, verify the CLI is available: +Nothing else. Don't explain OAuth, GCP projects, or scopes. If the user +comes back saying login failed, then mention `gws auth setup` as a second +step. -```bash -which gws || npm install -g @googleworkspace/cli -``` - -Then check auth status by running a lightweight command: - -```bash -gws calendar +agenda --today 2>&1 -``` - -If this returns an auth error (exit code 2), tell the user: - -> You need to authenticate with Google first. Run this in your terminal: -> -> ``` -> gws auth login -s calendar,gmail,drive,sheets,docs,tasks -> ``` -> -> This opens a browser for Google OAuth. After you sign in, try your request -> again. - -If `gws auth login` itself fails because no OAuth client is configured, guide -the user through `gws auth setup` which creates a Cloud project automatically -(requires `gcloud` CLI), or point them to the manual setup in the gws README. - -Do not attempt to run `gws auth login` yourself — it requires an interactive -browser session. Just tell the user what to run. - -## Be proactive - -When the user asks about their calendar, email, files, or tasks — act -immediately. Run the appropriate `gws` command without asking clarifying -questions first. Use sensible defaults: - -- Calendar: default to `primary` calendar, current timezone, this week -- Gmail: default to `userId: me`, unread inbox -- Drive: default to listing recent files -- Sheets: if they mention a spreadsheet name, search Drive for it first - -Only ask for clarification when genuinely ambiguous — like "which spreadsheet?" -when there are multiple matches, or when creating events that need specific -attendees. - -## Helper commands (use these first) - -The `+` prefixed commands are concise shortcuts that handle the common cases. -Prefer these over raw API commands. - -### Calendar +## Step 2: Act immediately -```bash -# Today's agenda -gws calendar +agenda --today +Do not ask clarifying questions. Run the command with sensible defaults: -# Tomorrow -gws calendar +agenda --tomorrow +- Calendar → `primary` calendar, user's timezone +- Gmail → `userId: me`, unread inbox +- Drive → search by name keywords the user mentioned +- Sheets → search Drive first if user gave a name, not an ID -# This week -gws calendar +agenda --week +Only ask for clarification when there are genuinely ambiguous results (e.g., +multiple spreadsheets matching a search). -# Next N days -gws calendar +agenda --days 7 +## Step 3: Pick the right commands -# Specific calendar -gws calendar +agenda --week --calendar "Work" +**Calendar**: See [references/calendar.md](references/calendar.md) +**Gmail**: See [references/gmail.md](references/gmail.md) +**Drive & Sheets & Docs**: See [references/drive-docs-sheets.md](references/drive-docs-sheets.md) +**Cross-service workflows**: See [references/workflows.md](references/workflows.md) -# Create an event (always confirm with the user first) -gws calendar +insert \ - --summary "Team standup" \ - --start "2026-03-25T10:00:00" \ - --end "2026-03-25T10:30:00" \ - --location "Room 3A" \ - --description "Weekly sync" \ - --attendee alice@example.com \ - --attendee bob@example.com \ - --meet # adds a Google Meet link +For any service not covered above, use `gws --help` to discover +available resources and methods. The raw syntax is: -# Quick add (natural language) -gws calendar events quickAdd \ - --params '{"calendarId": "primary", "text": "Lunch with Alice tomorrow at noon"}' ``` - -### Gmail - -```bash -# Unread inbox summary -gws gmail +triage - -# Triage with limit -gws gmail +triage --max 5 - -# Search -gws gmail +triage --query "from:boss subject:urgent" - -# Read a specific message -gws gmail +read --id MESSAGE_ID - -# Send email (always confirm with user first) -gws gmail +send \ - --to recipient@example.com \ - --subject "Meeting notes" \ - --body "Here are the notes from today's meeting..." \ - --attach ./notes.pdf - -# Reply -gws gmail +reply --message-id MSG_ID --body "Thanks, sounds good." - -# Forward -gws gmail +forward --message-id MSG_ID --to someone@example.com +gws --params '{"key": "val"}' --json '{"body": "data"}' ``` -### Drive +## Confirmation rules -```bash -# Upload a file -gws drive +upload ./report.pdf --name "Q1 Report" --parent FOLDER_ID +Confirm before actions that **affect other people**: +- Sending email +- Inviting attendees to events +- Sharing files or folders -# List recent files -gws drive files list --params '{"pageSize": 10}' - -# Search for files -gws drive files list --params '{"q": "name contains '\''budget'\''", "pageSize": 10}' - -# Download a file -gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o ./file.pdf -``` - -### Sheets - -```bash -# Read a range -gws sheets +read --spreadsheet "SPREADSHEET_ID" --range "Sheet1!A1:D10" - -# Append rows -gws sheets +append \ - --spreadsheet "SPREADSHEET_ID" \ - --json-values '[["Name", "Score"], ["Alice", 95]]' -``` +Do **not** confirm for actions that only affect the user: +- Blocking time on their own calendar +- Creating personal reminders or tasks +- Creating a private document or spreadsheet -### Docs - -```bash -# Append text to a document -gws docs +write --document "DOC_ID" --text "New section content here" - -# Read a document -gws docs documents get --params '{"documentId": "DOC_ID"}' -``` - -### Workflows (cross-service) - -```bash -# Morning briefing: today's meetings + open tasks -gws workflow +standup-report - -# Prep for your next meeting: agenda, attendees, linked docs -gws workflow +meeting-prep - -# Weekly overview: meetings + unread counts -gws workflow +weekly-digest -``` - -## Raw API commands (escape hatch) - -When helpers don't cover your use case, use the raw Discovery API syntax: - -``` -gws --params '{"key": "value"}' --json '{"body": "data"}' -``` - -All output is JSON by default. Use `--format table` for human-readable output. - -To discover what's available: - -```bash -gws calendar --help # list resources -gws schema calendar.events.list # inspect parameters for a method -``` - -### Useful raw examples - -```bash -# Free/busy query -gws calendar freebusy query \ - --json '{"timeMin": "2026-03-25T00:00:00Z", "timeMax": "2026-03-26T00:00:00Z", "items": [{"id": "primary"}]}' - -# List all calendars -gws calendar calendarList list - -# Get Gmail labels -gws gmail users labels list --params '{"userId": "me"}' - -# Create a spreadsheet -gws sheets spreadsheets create --json '{"properties": {"title": "Budget Tracker"}}' - -# Create a folder in Drive -gws drive files create --json '{"name": "Project Files", "mimeType": "application/vnd.google-apps.folder"}' - -# Export a Google Doc as PDF -gws drive files export --params '{"fileId": "DOC_ID", "mimeType": "application/pdf"}' -o ./doc.pdf -``` +The reason: asking "are you sure you want to block 2-4pm?" when the user +just told you to block 2-4pm is friction, not safety. ## Presenting results -Format `gws` JSON output into clean, readable summaries for the user: - -- **Calendar events**: group by day, show time + title + location. Flag conflicts. -- **Email triage**: show sender, subject, snippet. Highlight urgent items. -- **Drive files**: show name, type, modified date, sharing status. -- **Sheets data**: render as a Markdown table. - -Do not dump raw JSON at the user unless they specifically ask for it. - -## Rules - -- Never send email or create calendar events without explicit user confirmation. - Draft the content first and show it to the user for approval. -- If a command fails with exit code 2 (auth error), guide the user through - `gws auth login` with the appropriate scopes. -- If a command fails with exit code 1 (API error), read the error message and - adjust — common issues are wrong calendar ID, missing permissions, or quota - limits. -- Use `--format json` (the default) for programmatic processing, `--format table` - only when the user wants raw CLI output. -- For shell escaping: wrap JSON in single quotes, use double quotes around - ranges containing `!` (like `"Sheet1!A1:D10"`). +Format JSON output into readable summaries. Group calendar events by day. +Show email as sender + subject + snippet. Render sheets data as Markdown +tables. Never dump raw JSON unless the user asks for it. diff --git a/skills/gws/references/calendar.md b/skills/gws/references/calendar.md new file mode 100644 index 00000000..3400decf --- /dev/null +++ b/skills/gws/references/calendar.md @@ -0,0 +1,41 @@ +# Calendar Commands + +## Helper commands (prefer these) + +```bash +gws calendar +agenda --today +gws calendar +agenda --tomorrow +gws calendar +agenda --week +gws calendar +agenda --days 7 +gws calendar +agenda --week --calendar "Work" + +gws calendar +insert \ + --summary "Team standup" \ + --start "2026-03-25T10:00:00" \ + --end "2026-03-25T10:30:00" \ + --location "Room 3A" \ + --attendee alice@example.com \ + --meet + +gws calendar events quickAdd \ + --params '{"calendarId": "primary", "text": "Lunch with Alice tomorrow at noon"}' +``` + +## Common raw commands + +```bash +# Free/busy check +gws calendar freebusy query \ + --json '{"timeMin": "2026-03-25T00:00:00Z", "timeMax": "2026-03-26T00:00:00Z", "items": [{"id": "primary"}]}' + +# List all calendars +gws calendar calendarList list + +# Delete an event +gws calendar events delete --params '{"calendarId": "primary", "eventId": "EVENT_ID"}' + +# Update an event (patch) +gws calendar events patch \ + --params '{"calendarId": "primary", "eventId": "EVENT_ID"}' \ + --json '{"summary": "Updated title"}' +``` diff --git a/skills/gws/references/drive-docs-sheets.md b/skills/gws/references/drive-docs-sheets.md new file mode 100644 index 00000000..e9721ac0 --- /dev/null +++ b/skills/gws/references/drive-docs-sheets.md @@ -0,0 +1,57 @@ +# Drive, Docs & Sheets Commands + +## Drive + +```bash +# Search for files by name +gws drive files list --params '{"q": "name contains '\''budget'\''", "pageSize": 10}' + +# Search for spreadsheets specifically +gws drive files list --params '{"q": "mimeType='\''application/vnd.google-apps.spreadsheet'\'' and name contains '\''Q1'\''", "pageSize": 10}' + +# List recent files +gws drive files list --params '{"pageSize": 10, "orderBy": "modifiedTime desc"}' + +# Upload a file +gws drive +upload ./report.pdf --name "Q1 Report" + +# Download a file +gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o ./file.pdf + +# Export Google Doc as PDF +gws drive files export --params '{"fileId": "DOC_ID", "mimeType": "application/pdf"}' -o ./doc.pdf + +# Create a folder +gws drive files create --json '{"name": "Project Files", "mimeType": "application/vnd.google-apps.folder"}' +``` + +## Sheets + +```bash +# Read a range +gws sheets +read --spreadsheet "SPREADSHEET_ID" --range "Sheet1!A1:D10" + +# Append rows +gws sheets +append \ + --spreadsheet "SPREADSHEET_ID" \ + --json-values '[["Name", "Score"], ["Alice", 95]]' + +# Create a new spreadsheet +gws sheets spreadsheets create --json '{"properties": {"title": "Budget Tracker"}}' + +# Get spreadsheet metadata +gws sheets spreadsheets get --params '{"spreadsheetId": "ID"}' +``` + +## Docs + +```bash +# Create a document +gws docs documents create --json '{"title": "Meeting Notes"}' + +# Read a document +gws docs documents get --params '{"documentId": "DOC_ID"}' + +# Append text +gws docs +write --document "DOC_ID" --text "New section content here" +``` diff --git a/skills/gws/references/gmail.md b/skills/gws/references/gmail.md new file mode 100644 index 00000000..0cbb0ad6 --- /dev/null +++ b/skills/gws/references/gmail.md @@ -0,0 +1,37 @@ +# Gmail Commands + +## Helper commands (prefer these) + +```bash +gws gmail +triage +gws gmail +triage --max 5 +gws gmail +triage --query "from:boss subject:urgent" + +gws gmail +read --id MESSAGE_ID + +gws gmail +send \ + --to recipient@example.com \ + --subject "Meeting notes" \ + --body "Here are the notes..." \ + --attach ./notes.pdf + +gws gmail +reply --message-id MSG_ID --body "Thanks, sounds good." +gws gmail +reply-all --message-id MSG_ID --body "Agreed." +gws gmail +forward --message-id MSG_ID --to someone@example.com +``` + +## Common raw commands + +```bash +# Search messages +gws gmail users messages list --params '{"userId": "me", "q": "from:sarah subject:contract", "maxResults": 10}' + +# Get full message +gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}' + +# List labels +gws gmail users labels list --params '{"userId": "me"}' + +# List threads +gws gmail users threads list --params '{"userId": "me", "maxResults": 5}' +``` diff --git a/skills/gws/references/workflows.md b/skills/gws/references/workflows.md new file mode 100644 index 00000000..fa039fc8 --- /dev/null +++ b/skills/gws/references/workflows.md @@ -0,0 +1,39 @@ +# Cross-Service Workflows + +## Built-in workflows + +```bash +# Morning briefing: today's meetings + open tasks +gws workflow +standup-report + +# Prep for next meeting: agenda, attendees, linked docs +gws workflow +meeting-prep + +# Weekly overview: meetings + unread counts +gws workflow +weekly-digest + +# Convert email to task +gws workflow +email-to-task + +# Announce a file in Chat +gws workflow +file-announce +``` + +## Manual multi-step patterns + +When a built-in workflow doesn't fit, chain commands. Examples: + +**"Check email then schedule with important senders":** +1. `gws gmail +triage` → get unread emails +2. Pick the important senders from the results +3. `gws calendar +insert --summary "..." --attendee sender@...` → create event (confirm with user first since it involves attendees) + +**"Find a spreadsheet and extract data":** +1. `gws drive files list --params '{"q": "name contains '\''sales'\''..."}'` → find the file +2. `gws sheets +read --spreadsheet "ID" --range "Sheet1!A1:Z100"` → read the data +3. Present the relevant numbers to the user + +**"Block time and reschedule a conflict":** +1. `gws calendar +agenda --today` → find existing events +2. `gws calendar +insert --summary "Deep Work" --start ... --end ...` → create the block (no confirmation needed for personal blocks) +3. `gws calendar events patch --params '{"calendarId": "primary", "eventId": "..."}' --json '{"start": ..., "end": ...}'` → move the conflicting event From efb84df524c656795057168798ea0059273b833b Mon Sep 17 00:00:00 2001 From: Maximilian Noller Date: Sun, 22 Mar 2026 18:09:55 +0100 Subject: [PATCH 3/3] chore: simplify gws auth guidance, drop setup fallback 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) --- skills/gws/SKILL.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/skills/gws/SKILL.md b/skills/gws/SKILL.md index 269c5d0d..7d99c9b4 100644 --- a/skills/gws/SKILL.md +++ b/skills/gws/SKILL.md @@ -38,9 +38,8 @@ If `auth_method` is `"none"`, tell the user: > Run `gws auth login` in your terminal to connect your Google account. -Nothing else. Don't explain OAuth, GCP projects, or scopes. If the user -comes back saying login failed, then mention `gws auth setup` as a second -step. +That's it. Don't explain OAuth, GCP projects, scopes, or alternatives. +The default login flow works for both personal Gmail and Workspace accounts. ## Step 2: Act immediately