AGENT SKILL

gworkspace-cli

Google Workspace via the gws CLI (Drive/Sheets/Docs/Gmail/Calendar/Chat/Admin). Use when the agent needs to read or write any Workspace data such as Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.

License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
gworkspace-cli
license
MIT
description
Google Workspace via the gws CLI (Drive/Sheets/Docs/Gmail/Calendar/Chat/Admin). Use when the agent needs to read or write any Workspace data such as Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.

03 SKILL.md 正文

Google Workspace CLI (gws)

Single-command access to Google Workspace APIs through one gws binary on $PATH. Use when the agent needs to read or write any Workspace data: Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.

When to Use

This skill covers using gws to read/write Workspace data once it is installed and authenticated. The boundary cases worth flagging:

  • Install / auth not done (gws missing, or gws auth status reports no creds) → don't improvise the setup; surface docs/integrations/gworkspace-cli-setup.md and walk the user through it.
  • The admin group (users, groups, org units) needs Workspace-admin credentials — out of reach for an ordinary delegated account; don't reach for it on a normal user's behalf.

Setup

If gws is not installed, or gws auth status reports no active credentials — open docs/integrations/gworkspace-cli-setup.md and walk the user through install, auth, and permission-allowlist steps. Do not try to install or authenticate without surfacing the guide.

Top-level command groups

Group Purpose
drive Files, folders, sharing, copy/move/trash
sheets Spreadsheets, values, batch updates
docs Documents, structured content edits
gmail Threads, messages, labels, send
calendar Calendars, events, agenda
chat Spaces, messages
admin Users, groups, org units (Workspace admin only)

Discovery

Commands are generated dynamically from Google's Discovery Service plus hand-crafted helpers (prefixed +):

gws --help                    # all groups
gws <group> --help            # methods in a group
gws <group> <method> --help   # params for a single method

When unsure which method fits — start from gws <group> --help, then narrow.

Common patterns

Read a range:

gws sheets spreadsheets values get \
  --params '{"spreadsheetId":"<id>","range":"Sheet1!A:Z"}' \
  --format csv

Append a row (dates and formulas parsed):

gws sheets spreadsheets values append \
  --params '{"spreadsheetId":"<id>","range":"Sheet1!A1","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["2026-05-18","value"]]}'

Find a file by name:

gws drive files list \
  --params '{"q":"name = '\''Report'\'' and trashed = false","fields":"files(id,name)"}'

Safety & conventions

  • No secrets in code or examples. Auth state lives in ~/.config/gws/ (AES-256-GCM at rest); never embed tokens, client secrets, or service-account keys.
  • Identifiers via env, not hardcode. Spreadsheet IDs, folder IDs, etc. — read from environment or config files, not literal strings.
  • USER_ENTERED for values that contain dates, numbers, or formulas; RAW only for verbatim strings.
  • Append-only for journals. Use values append (not update) for transaction logs; never overwrite history.
  • Snapshot before destructive writes. gws drive files copy the spreadsheet/doc before bulk writes to critical sheets.
  • CLI resolves via $PATH. No hardcoded install paths; if gws is missing, surface the setup guide.

Anti-patterns

  • Hardcoding spreadsheet/folder IDs in scripts or skill content.
  • Writing tokens or OAuth secrets into the repo or skill files.
  • Using RAW when the values include dates or formulas — they end up as plain strings.
  • Overwriting an append-only journal sheet with values update.
  • Calling gws from a fully qualified path (/usr/local/bin/gws) — break portability.
  • Bulk writes without a prior gws drive files copy snapshot.

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3