gws-gmail-forward Skill: Forward Gmail Messages From Your Assistant

Lets your coding assistant forward a Gmail message to new people by running the gws command line tool.

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

gws-gmail-forward teaches your assistant to run gws gmail +forward. You give it a Gmail message ID and the people to forward it to. It can add a note, CC and BCC, extra attachments, or save the forward as a draft instead of sending it.

The skill is a short instruction file. The gws tool sends the mail, so you must install gws and sign in to Google first. The skill tells the assistant to read the gws-shared skill before it runs anything.

Good for

Claude Code or Codex users who already work in the terminal and want mail handled there
People who forward the same kinds of messages often and want it scripted
Teams that use Google Workspace and want an assistant to draft forwards for review

Install gws-gmail-forward

Claude Code

Copy this prompt.

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

npm install -g @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+.

Do steps 1 to 3 in order. The skill only gives your assistant instructions. The gws tool does the work, and it needs a Google sign-in. gws auth setup needs the gcloud CLI to create a Google Cloud project for you; without gcloud, use the manual setup in the README. The README also lists a GitHub Releases download, Homebrew and cargo as other ways to get gws.

From the project README. Source.

What's in the skill

When it loads

Gmail: Forward a message to new recipients.

Sections in SKILL.md

Usage
Flags
Examples
Tips
See Also

Key facts

Author: googleworkspace org (the README says it is not an officially supported Google product)
Repo: googleworkspace/cli
Installs on skills.sh: 34,097 as of 2026-11-02
GitHub stars: 32,038 for the whole googleworkspace/cli repo, 2026-11-02
License: Apache-2.0 (README)
Last commit to the repo: 2026-10-30
What is inside: 1 file (SKILL.md). It points to the separate gws-shared skill.
Needs: The gws command line tool (Node.js 18+ for the npm route), a Google account and a Google Cloud project for sign-in
Also installs: gws-shared, which the skill tells the assistant to read first for sign-in, flags and safety rules
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn (2026-11-02)

What it includes

Forwards a Gmail message to new recipients
Takes a Gmail message ID and a comma-separated list of recipients, then sends the forward. The original message goes along with its sender, date, subject and recipients.
Try: “Forward Gmail message 18f1a2b3c4d to dave@example.com with the note "FYI see below".”
Runs code · gws gmail +forward
Saves the forward as a draft instead of sending it
Use this when you want to read the forward in Gmail before it goes out.
Write · --draft
Shows the request that would be sent without sending it
A preview of the call. The skill lists it as a flag; nothing is sent when it is set.
--dry-run
Adds a note above the forwarded message
The note is plain text by default. With --html the forwarded block keeps Gmail formatting and inline images, and you pass fragment tags such as <p> and <b>.
Write · --body and --html
Adds files, or leaves out the original attachments
Original attachments are included by default. The combined size of original and added attachments is limited to 25MB.
Files · --attach and --no-original-attachments
Copies others, hides recipients, or sends from an alias
--from is for a send-as address or alias; leave it out to use the account default.
Write · --cc, --bcc and --from

From the official docs

Permissions

Medium risk

This skill makes your assistant send email from your Google account. Approve each run yourself, or ask for a draft first.

What it can do

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

Watch out for

It sends real email from your account
gws gmail +forward sends the message unless you pass --draft or --dry-run. Check the recipients and the forwarded content before you approve each run. github.com
Forwards can carry attachments
Original attachments are included by default, up to 25MB combined. Add --no-original-attachments if the files should stay private. github.com
Setup installs a global npm package
The npm route downloads the gws binary from GitHub Releases. The README also says to expect breaking changes before v1.0, so pin what you rely on. github.com
You need a Google Cloud project to sign in
gws uses OAuth credentials from your own Google Cloud project. If the consent screen is unverified, Google caps the scopes you can pick, so choose individual services with gws auth login -s. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. --dry-run shows the request without sending, and --draft saves a draft instead of sending.
Talks to	Google Workspace APIs, called by the gws tool. Anything the assistant reads from your account goes to your AI provider as part of the chat
Sign-in and keys	gws encrypts saved credentials (AES-256-GCM) with a key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is chosen.
Scopes	Whatever Google permissions you approve when you run gws auth login

Questions

What does gws-gmail-forward do?

It makes your assistant forward a Gmail message with gws gmail +forward. You supply the message ID and the recipients. It can add a note, CC and BCC, and attachments, or save the forward as a draft.

How do I install gws-gmail-forward?

Use the install box at the top of this page and run all three steps. The skill does nothing without the gws tool and a Google sign-in. The skills command also adds gws-shared, which the skill tells the assistant to read first.

Does it need a Google Cloud project or an API key?

It needs a Google Cloud project, because gws signs in with OAuth credentials from one, according to the README. gws auth setup can create it if you have the gcloud CLI. Without gcloud, follow the README's manual setup.

Is gws-gmail-forward safe to use?

It sends real email from your Google account, so check the recipients before you approve each run. The shared rules tell the assistant to confirm write commands first and to prefer --dry-run. Use --draft if you want to read the forward in Gmail before it goes out.

Can I use it in the Claude app or Claude.ai?

The README does not document that. The skill tells the assistant to run gws shell commands, so it fits an assistant that can run commands on a machine where gws is installed and signed in, such as Claude Code or Codex.

How is it different from the gws-gmail skill?

The SKILL.md points to gws-gmail for all send, read and manage email commands. This skill covers only +forward. The README lists the other Gmail helpers: +send, +reply, +reply-all, +triage and +watch.

Is gws an official Google tool?

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

Information

updated Nov 2, 2026

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

googleworkspace/cli skills.sh

Sources

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

Show all 4