Open source Agent Skill for operating gws safely, predictably, and with
schema-driven request construction.
Documentation • Quick Start • Examples • Contributing
This repository packages a focused skill, gws-cli, that teaches an agent how to install, authenticate, inspect, and safely execute commands from the upstream googleworkspace/cli project.
It is intentionally narrower than the upstream repository. Instead of shipping a large skill catalog, it provides one curated entry point for teams that want:
- a consistent
gws schema-first discovery workflow - explicit safety rules for write operations
- practical authentication guidance for local, CI, and service-account usage
- lightweight OSS documentation suitable for GitHub and skills ecosystems
Google Workspace automation usually breaks down in one of three places:
- agents guess API parameter names instead of inspecting the schema
- write operations run without explicit confirmation or clear scope checks
- authentication guidance is fragmented across local, headless, and CI flows
This skill addresses those problems by turning gws into a documented,
repeatable operating model for agents.
The skill follows a fixed execution pattern:
| Step | What the agent should do | Why it matters |
|---|---|---|
| 1 | Verify gws is installed |
Prevents command failures before API work starts |
| 2 | Check auth status | Avoids guessing credentials or scopes |
| 3 | Inspect service help or gws schema |
Builds requests from the real API surface |
| 4 | Prefer read operations first | Reduces accidental state changes |
| 5 | Confirm writes explicitly | Enforces human approval for risky operations |
| 6 | Execute with structured output | Makes results easier to parse and audit |
- Node.js with
npmavailable gwsinstalled and available onPATH- network access to Google APIs
- an authenticated Google Workspace or Google Cloud context
npx skills add fabioeloi/gws-cli-skillOr install from the repository URL:
npx skills add https://github.com/fabioeloi/gws-cli-skillnpm install -g @googleworkspace/cli# Check local prerequisites
bash gws-cli/scripts/check-prereqs.sh
# Inspect the service surface
gws drive --help
gws schema drive.files.list
# Execute a safe read-only command
gws drive files list --params '{"pageSize": 10}' --format jsongws sheets --help
gws schema sheets.spreadsheets.values.get
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A:C"}' \
--format jsongws schema sheets.spreadsheets.create
gws sheets spreadsheets create \
--json '{"properties": {"title": "Q1 Budget"}}' \
--format jsongws drive +upload ./report.pdf --parent FOLDER_IDTreat helper commands that mutate state exactly like raw write operations: confirm the target, scope, and expected effect before running them.
gws gmail +triage --query 'label:inbox newer_than:7d'gws gmail +send \
--to [email protected] \
--subject 'Weekly status' \
--body 'Budget review is complete.'gws calendar +agenda --calendar primary --days 7
gws schema calendar.events.insertMore concrete Gmail, Drive, Docs, and Calendar workflows are documented in docs/usage.md.
gws-cli/
├── SKILL.md
├── references/
│ └── REFERENCE.md
└── scripts/
└── check-prereqs.sh
docs/
├── architecture.md
├── authentication.md
├── publishing.md
└── usage.md
| Document | Description |
|---|---|
| gws-cli/SKILL.md | The operational skill loaded by compatible agents |
| gws-cli/references/REFERENCE.md | Technical reference for flags, auth, helpers, and safe execution |
| docs/usage.md | Day-to-day usage patterns and command design rules |
| docs/authentication.md | Local, service-account, and CI authentication guidance |
| docs/architecture.md | Repository structure and documentation boundaries |
| docs/publishing.md | How the skill is distributed through GitHub and the skills ecosystem |
| CHANGELOG.md | Version history and notable documentation changes |
| Metric | Target | Why it exists |
|---|---|---|
| Skill validation | 100% pass | Guarantees spec compliance for gws-cli/SKILL.md |
| Markdown lint | 100% pass | Keeps public documentation consistent and maintainable |
| Schema-first examples | 100% of write examples | Reduces guessed parameters and malformed requests |
| Secret exposure in docs | 0 | Prevents unsafe copy-paste patterns |
- Initial OSS release for a single
gws-cliskill - Public repository documentation and modular docs pages
- Add more concrete examples for Gmail, Drive, Docs, and Calendar
- Add a troubleshooting matrix for common auth and API failures
- Recheck and document the current public skills.sh listing status
The repository is public on GitHub and can be installed directly from the repository URL.
As of 2026-03-06, the public skills.sh listing still returned 404 during the latest verification pass. That appears to be an indexing delay outside this repository rather than a packaging problem with the skill itself.
If the public listing is not available yet, use the direct install path:
npx skills add https://github.com/fabioeloi/gws-cli-skillpython3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref
skills-ref validate gws-cli
find . -name '*.md' -not -path './.specstory/*' -not -path './.venv/*' -print0 | xargs -0 npx [email protected]Contributions are welcome as long as they keep the repository focused on safe,
schema-driven gws usage. See CONTRIBUTING.md for the
development workflow, validation steps, and authoring rules.
- agentskills.io for the open Agent Skills format
- skills.sh for ecosystem distribution and discovery
- googleworkspace/cli for the upstream CLI and command model this skill is built around
- fabioeloi/omni-architect for the documentation structure used as editorial reference
This project is licensed under the MIT License.