gws-gmail Skill for Claude Code: Triage, Read, Reply to and Send Gmail

Lets your assistant triage, read, reply to, forward and send Gmail through the gws command line.

Installs: 83.1K; on skills.sh
Stars: 32K; on GitHub
Updated: Oct 2026; last repo commit

gws-gmail makes your assistant work with Gmail by running gws gmail commands. It lists seven helper commands: send, triage (an unread inbox summary), reply, reply-all, forward, read and watch for new mail. It also exposes the Gmail API resources for drafts, history, labels, messages, settings and threads.

It needs the gws command line installed and signed in, and its first line tells the assistant to read the gws-shared skill for sign-in, global flags and security rules. Each helper command has its own skill file in the same repo. The README says gws is not an officially supported Google product and warns to expect breaking changes before v1.0. The folder holds one SKILL.md and no scripts.

Good for

People who want Claude to summarize and triage their inbox
Developers scripting Gmail from the terminal
Workspace users already using the gws CLI for Drive or Calendar

Install gws-gmail

Claude Code

Copy this prompt.

Install the gws-gmail skill in Claude Code. Run this command:

npx skills add https://github.com/googleworkspace/cli

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 18+.

The gws-gmail skill calls the gws command and tells the assistant to read gws-shared for sign-in and safety rules. The first command is the README's install-all command: it adds 100+ gws skills, including gws-shared and the seven Gmail helper skills. To take only this skill, the README shows npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail, but that path is the gws-gmail folder only, and gws-shared is a separate folder in the repo. Run gws auth setup once if you have gcloud; the README covers a manual OAuth setup if you do not.

From the project README. Source.

What's in the skill

When it loads

Gmail: Send, read, and manage email.

Sections in SKILL.md

Helper Commands
API Resources
users
Discovering Commands

Key facts

Author: Google Workspace (googleworkspace/cli)
Repo: googleworkspace/cli
Installs on skills.sh: 83,071 (Nov 2, 2026)
GitHub stars (whole repo): 32,038 (Nov 2, 2026)
License: Apache-2.0
Last repo commit: Oct 30, 2026
Files in the skill folder: 1 file: SKILL.md
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn
Skill version in SKILL.md: 0.22.5
Needs: The gws command on your PATH, signed in with gws auth login
Shared skill: gws-shared, for sign-in, global flags and security rules

What it includes

Send an email
Write · +send
Show an unread inbox summary: sender, subject, date
Network · +triage
Reply to a message, with threading handled for you
Write · +reply, +reply-all
Forward a message to new recipients
Write · +forward
Read a message and extract its body or headers
Network · +read
Watch for new emails and stream them as NDJSON
Network · +watch
Call any Gmail API resource: drafts, labels, messages, settings, threads
Write · gws gmail <resource> <method>
Inspect a method's parameters before calling it
Read · gws schema gmail.<resource>.<method>

From the official docs

Permissions

High risk

This skill can send email and read your mailbox through your Google account. Use narrow sign-in scopes and approve each outgoing message yourself.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can send, reply to and forward email as you
Check every draft before the assistant sends it. The gws-shared skill says to always confirm with the user before write or delete commands. github.com
It can reach more than your inbox
The Gmail API resources it lists include messages, drafts, labels, threads and settings. Pick narrow scopes when you run gws auth login. github.com
The CLI is not an official Google product
The README says so and warns to expect breaking changes before v1.0. Test on a spare account first. github.com

Technical details

Talks to	Google Gmail API through the gws command
Sign-in and keys	The README lists encrypted credentials from gws auth login, with a plaintext credentials.json file as a lower-priority option.
Scopes	Your Gmail account, through Google OAuth scopes you choose at sign-in

Questions

What does the gws-gmail skill do?

It teaches your assistant the gws gmail commands: triage, read, reply, reply-all, forward, send and watch. The assistant runs them on your machine with your Google sign-in.

How do I install the gws-gmail skill?

Use the install box at the top of this page. It installs the gws skills, including gws-shared and the Gmail helper skills this one points to. You also need the gws command installed and signed in.

Do I need the gws command line?

Yes. The frontmatter lists gws as a required binary, and the SKILL.md opens with a prerequisite to read gws-shared for sign-in. The README covers install options and Google sign-in.

Can it send or delete email?

It can send, reply to and forward mail. It also exposes Gmail API resources for messages, drafts, labels, threads and settings. The gws-shared skill says: Always confirm with user before executing write/delete commands.

Is gws an official Google tool?

The README says it is not an officially supported Google product, and that you should expect breaking changes before v1.0.

Is the gws-gmail skill safe to install?

The skill file is a single markdown page with no bundled scripts. What matters is what you let gws do: it signs in to your Google account and can send mail. Choose narrow scopes and test on a spare account first.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-gmail

googleworkspace/cli skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

googleworkspace/cli README · github.com
gws-shared SKILL.md · github.com
gws-gmail SKILL.md · github.com
gws-gmail on skills.sh · skills.sh