Guide · Agent skill
How to use the Gmail Assistant (gws) agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-gmail skill is a set of instructions that teaches an AI agent how to work with Gmail through the gws command-line tool. Once it is installed and gws is set up with your Google account, the agent can summarise unread mail, read messages, draft and send email, and watch for new messages. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to check before letting it send anything.
Gmail Assistant (gws)googleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws. Install the gws command-line tool and confirm your Google account is authenticated through it, following the gws-shared skill.
- 2Download the skill. Download the ZIP for gws-gmail from this page and unzip it.
- 3Place the folder. Move the unzipped folder into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
- 4Confirm the commands. Run gws gmail --help to see the available resources and methods.
- 5Ask for a read-only task. Request an unread summary or a message read so you can check the agent is working with the right mail.
- 6Review before sending. When you ask for a send or reply, check the recipients and text the agent shows you before it runs.
What the Gmail skill makes the agent do
An agent skill is a folder with a SKILL.md file that tells an AI agent how to perform a task with a specific tool. This skill covers Gmail. It tells the agent which gws commands exist for email and how to use them.
The skill lists seven helper commands: +send to send an email, +triage to show an unread inbox summary with sender, subject and date, +reply and +reply-all to answer a message with threading handled automatically, +forward to pass a message to new recipients, +read to read a message and extract its body or headers, and +watch to watch for new emails and stream them as NDJSON.
- Summarise unread mail (+triage)
- Read a message's body or headers (+read)
- Draft and send email (+send)
- Reply, reply-all or forward with threading handled (+reply, +reply-all, +forward)
- Watch for new messages (+watch)
Install the Gmail skill
Download the ZIP for this skill from this page and unzip it. To make the skill available to Claude Code for all your projects, put the unzipped folder in ~/.claude/skills/. To make it available only inside one project, put it in that project's .claude/skills/ folder.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you start
The skill needs the gws command-line tool (the googleworkspace CLI) installed on the machine where the agent runs, and it needs local shell access so the agent can run gws commands. Google account authentication must be configured through gws. The skill refers to a separate gws-shared skill for authentication, global flags and security rules. If that file is missing, the source says to run gws generate-skills to create it.
The skill's metadata lists gws as a required binary. It runs scripts and uses the network, so it is not a passive document.
- gws command-line tool installed
- Google account authenticated via gws (see the gws-shared skill)
- Local shell access to run gws commands
Ask for Gmail tasks in plain language
You do not need to name the command. Describe what you want and the agent should pick the matching helper. Be specific about who, what and when, because the agent will act on your account. For sending, say exactly who the recipients are and what the message should say.
Before the agent acts, it can look up exact options. The skill points it to built-in help and schema commands, so it can check required parameters rather than guessing.
- "Summarise my unread email from today."
- "Read the message from Sam about the invoice and tell me what it asks for."
- "Draft a reply to the last message from the recruiter and show it to me before sending."
- "Forward the shipping confirmation to my landlord."
- "Watch my inbox and tell me when a message arrives from my bank."
gws gmail --help
gws schema gmail.<resource>.<method>Safety notes: scripts, network and sending
Sends are real. Once an email is delivered it cannot be taken back through this skill, so review any draft or send request before the agent runs it. The skill itself is documentation for the agent; the actions it triggers run gws commands that use the network and your authenticated Google account.
Only install skills you trust, and keep gws authentication limited to the account you intend the agent to use.
- Ask the agent to show the recipients and body before sending.
- Check the gws-shared skill for authentication and security rules.
- Use +triage and +read first to confirm what the agent is working with.
Tips for getting reliable results
If the agent guesses at flags, ask it to run the schema command for the method first. The skill tells the agent to use gws schema output to build its --params and --json flags. If the skill is not found, check that the folder sits in the correct skills directory and that the SKILL.md file is inside it.
- Start with read-only requests such as summaries before asking for sends.
- Name the message or sender clearly so the agent reads the right thread.
- Let the agent use +reply rather than building threads by hand; it handles threading automatically.
gws gmail <resource> <method> [flags]What people use it for
- Triage a busy inbox into a short list of unread senders, subjects and dates.
- Read a long message and pull out the body or headers you need.
- Draft and send replies that stay in the original thread.
- Forward a message to new recipients without copying it by hand.
- Watch for new messages from a specific sender and have them streamed to the agent.
Frequently asked questions
How do I install the gws-gmail agent skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
What do I need before the Gmail skill works?
You need the gws command-line tool installed, your Google account authenticated through gws, and local shell access so the agent can run gws commands. The skill refers to the gws-shared skill for authentication.
Is the gws-gmail skill free?
The skill is licensed under Apache-2.0, as listed on this page. Check the upstream repository for the license terms and any other costs of the gws tool itself.
Can the agent send emails without asking me?
The skill gives the agent the ability to send email, and sends are irreversible once delivered. Ask the agent to show you the recipients and body first, and only approve sends you have reviewed.
What if the agent says the skill or gws is missing?
Check that the skill folder is in the correct skills directory and contains SKILL.md. If the gws-shared file is missing, the source says to run gws generate-skills to create it. Confirm gws is installed and authenticated.
Does this skill work with email providers other than Gmail?
No. The skill covers Gmail through the gws tool. If you need a different mail provider, you will need a different skill or tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits people who want an agent to triage and reply to a busy Gmail inbox, and developers who already use gws and want to automate Gmail tasks. It is a poor fit if you are uncomfortable with an agent sending email from your account without review, or if you do not have gws installed and authenticated. Start with read-only tasks and review every send.
Download the skill