Guide · Agent skill

How to use the Gmail Forward agent skill (gws-gmail-forward)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The gws-gmail-forward skill teaches an AI agent how to forward an existing Gmail message to one or more new recipients by running the gws command-line tool. It is aimed at people who forward Gmail regularly and want an agent to do it from a terminal or chat, and at developers who already use gws with an authenticated Gmail account. After this guide you will know what the skill needs, how to install it, how to phrase requests so the agent uses it, and how to preview or draft a forward before anything is sent.

Gmail Forwardgoogleworkspace/cli · Apache-2.0 Download the skill

Quick start

1Install the gws tool. Install the gws command-line tool and confirm it is on your PATH. The skill cannot work without it.
2Authenticate your Google account. Connect a Google account with Gmail access, following the authentication steps described in the gws-shared skill.
3Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
4Find the message ID. Get the Gmail message ID of the email you want to forward. The forward command requires it.
5Preview or draft first. Ask the agent to use --dry-run or --draft so you can check the request before anything is sent.
6Send the forward. Once the preview looks right, ask the agent to forward the message to the recipients, adding a note, CC or BCC if needed.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. This skill is named gws-gmail-forward and its description is: Gmail: Forward a message to new recipients.

Once installed, the agent can forward an existing Gmail message using the gws command-line tool. The basic form needs the Gmail message ID and at least one recipient address. The agent can also add a note above the forwarded message, attach extra files, add CC or BCC recipients, include or exclude the original attachments, preview the request with --dry-run, or save the forward as a draft with --draft.

What you need before you install

The skill does not forward mail on its own. It depends on the external gws tool, so the following must be in place first:

The gws command-line tool, installed and available on your PATH.
A Google account authenticated with Gmail access. The skill's source points to the gws-shared skill for authentication details.
The Gmail message ID of the message you want to forward.
If the gws-shared skill file is missing, the source says to run gws generate-skills to create it.

Install the skill from the download

Download the ZIP for this skill from this page and unzip it. Then place the folder in one of these locations:

Personal use: unzip into ~/.claude/skills/
Single project: unzip into the project's .claude/skills/ folder
Claude apps: upload the skill under Settings → Capabilities → Skills

Trigger the skill with a natural request

You do not need to type the flags yourself. Ask the agent in plain language and include the message ID and the recipient. The agent maps your request onto the gws command. Name the message ID explicitly, because the forward needs it.

If you want a safe check first, say so. Asking for a preview or a draft tells the agent to use --dry-run or --draft instead of sending.

Forward message 18f1a2b3c4d to dave@example.com with the note FYI see below.
Forward message 18f1a2b3c4d to dave@example.com and copy eve@example.com. Show me the request first.
Save a forward of message 18f1a2b3c4d to dave@example.com as a draft so I can review it.

Command reference and examples

The underlying command is gws gmail +forward. Required flags are --message-id and --to. Multiple recipients in --to, --cc or --bcc are comma-separated. The examples below are taken from the skill source.

--body adds a note above the forwarded message; plain text by default, or HTML with --html.
--attach or -a adds a file and can be repeated.
--no-original-attachments leaves out the original message's files.
--from sets a send-as or alias address; omit it to use the account default.
--dry-run shows the request without executing it.
--draft saves the forward as a draft instead of sending it.

gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --body 'FYI see below'
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --cc eve@example.com
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --body '<p>FYI</p>' --html
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com -a notes.pdf
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --no-original-attachments
gws gmail +forward --message-id 18f1a2b3c4d --to dave@example.com --draft

Safety notes: scripts and network access

This skill runs scripts and uses the network. Forwards are sent from the connected Google account and cannot be undone once sent. Before you rely on it, check exactly which recipients and attachments the agent will use. Use --dry-run to see the request, or --draft to save it for review.

Only forward mail on behalf of someone when you are authorised to do so.
Combined size of the original message's attachments and your extra attachments is limited to 25MB. Larger forwards will fail.
The skill's source describes gws-shared for global flags and security rules. Read it before use.

Tips for reliable forwards

These points come from the skill's tips section and explain how the forward behaves.

The forward includes the original message with sender, date, subject and recipients.
Original attachments are included by default, matching Gmail web behaviour.
In plain-text mode, inline images are not included. With --html, inline images are kept via cid: references.
With --html, use fragment tags such as <p>, <b> and <a>. No <html> or <body> wrapper is needed.
Use --draft when you want to review before sending.

What people use it for

Forwarding a receipt or invoice to an accountant with a short note above it.
Passing a thread to a colleague and copying a manager, using --cc.
Adding an extra PDF to a forwarded message with -a.
Drafting a forward for review before sending, using --draft.
Automating forwards in a script for a developer workflow that already uses gws.

Frequently asked questions

How do I install the gws-gmail-forward skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills. The gws command-line tool must also be installed and on your PATH.

What do I need to use the Gmail forward skill?

You need the gws command-line tool installed and on your PATH, a Google account authenticated with Gmail access, and the Gmail message ID of the message to forward. The skill does not forward mail without gws.

Is the gws-gmail-forward skill free?

The source material for this skill is licensed under Apache-2.0. It does not state pricing, so check the project's repository for any cost details of the gws tool itself.

Can I preview a forward before it is sent?

Yes. The --dry-run flag shows the request that would be sent without executing it. You can also use --draft to save the forward as a draft instead of sending it.

Why did my forward fail?

A common cause in the source is size: the combined size of the original and extra attachments is limited to 25MB, and larger forwards will fail. Also confirm that gws is installed, on your PATH, and authenticated to the correct Google account.

Does the forward include the original attachments?

Yes, by default. Use --no-original-attachments to forward without the original message's files. With --html, inline images are preserved, while in plain-text mode they are not included.

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 forward Gmail often and want an agent to handle it from a terminal or chat, and developers already using the gws CLI with Gmail authenticated. Use --dry-run or --draft whenever you are unsure, because forwards cannot be recalled once sent. If you do not have gws set up, or you need to send mail on someone else's behalf without authorisation, pick a different approach.

Download the skill