Skip to content
Get packs

Guide · Agent skill

How to use the Forward Labeled Gmail Messages agent skill

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

This guide explains what the Forward Labeled Gmail Messages agent skill does, how to install it, and how to ask an AI agent to use it. An agent skill is a folder with a SKILL.md file that gives an AI agent a repeatable workflow for a specific task. After reading this page you will know what the skill needs, how to set it up, and what to check before running it on real mail.

Forward Labeled Gmail Messagesgoogleworkspace/cli · Apache-2.0

Quick start

  1. 1Install the gws CLI. Install the gws command-line tool and authenticate it with your Google account. The skill cannot work without it.
  2. 2Load the gws-gmail skill. Make sure the gws-gmail skill is loaded alongside this skill.
  3. 3Create or choose a label. Apply a Gmail label named needs-review to the messages you want forwarded, or edit the query to use your own label.
  4. 4Install this skill. Download the ZIP, unzip it, and place the folder in ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
  5. 5Make a request and check the result. Ask the agent in plain language to forward your labelled emails to a named address, then check the recipient and content of what was sent.

What does the skill make the agent do?

The skill teaches an agent a short workflow for Gmail. The agent searches your mailbox for messages with a specific label, reads the content of each match, and sends a new email containing that content to an address you choose. The example in the source uses a label called needs-review and forwards to manager@company.com.

  • Find messages carrying the label (the example uses needs-review).
  • Read the content of each matching message.
  • Send a new email with that content to another address.

What you need before installing

The skill does not access Gmail on its own. It relies on the separate gws command-line tool (the googleworkspace CLI), which must be installed and authenticated with a Google account. The skill also requires the gws-gmail skill, which must be loaded alongside this one. You also need a Gmail label named needs-review, or you can edit the search query to match your own label.

  • gws command-line tool, installed and authenticated with a Google account
  • gws-gmail skill, loaded together with this skill
  • A Gmail label named needs-review, or an edited query for your own label

How do you install the skill?

Download the ZIP file from this page and unzip it. Place the resulting skill folder in one of two locations: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want the skill only inside one project.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need to type a command to use the skill. Describe the task in plain language and name the label and recipient. The agent decides whether this skill fits the request, so mention Gmail and the label clearly. Check the first run closely to confirm the agent picked the right messages and recipient.

  • Forward my needs-review emails to manager@company.com.
  • Find emails labelled needs-review and send their contents to my supervisor.
  • Pass on any Gmail messages with the needs-review label to manager@company.com for review.

What commands does the workflow run?

The skill's steps use three gws commands. The first lists messages matching the label query, the second gets the content of one message by its ID, and the third sends the new email. The agent fills in the message ID and the subject and body from the earlier results.

Note that the third step sends a new email with the message content. It is not a native Gmail forward.

gws gmail users messages list --params '{"userId": "me", "q": "label:needs-review"}' --format table

What safety points should you check?

This skill runs scripts and uses the network. The steps show no confirmation step, so an email can be sent to the wrong address or can contain sensitive content without anyone reviewing it first. Message bodies are copied into new emails with no filtering.

Do not use this skill to forward confidential or personal mail to outside parties. Test with a harmless label and your own address before relying on it.

  • Emails are sent without a preview or confirmation step.
  • Message bodies are copied as they are, with no filtering.
  • Use a test label and your own address first.

What people use it for

  • Passing review requests labelled needs-review to a supervisor or colleague.
  • Managers forwarding mail that staff have flagged for their decision.
  • Developers studying a scriptable example that combines the gws CLI with Gmail.

Frequently asked questions

Is the Forward Labeled Gmail Messages skill free?

The source does not state a price or licence terms for the skill itself beyond its licence, which is listed as Apache-2.0. Check the licence in the repository before you use or redistribute it.

What do I need to run this agent skill?

You need the gws command-line tool installed and authenticated with a Google account, the gws-gmail skill loaded alongside this one, and a Gmail label named needs-review or an edited query for your own label. Without the gws CLI the skill cannot work.

Where do I install an agent skill?

Unzip the downloaded skill folder into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does this skill forward the original Gmail message?

No. The third step sends a new email with the original subject prefixed by FW: and the message body copied in. It is not a native Gmail forward, so the sender and headers of the original are not preserved by the step as written.

Can the skill send an email to the wrong person?

Yes, it is possible. The steps have no confirmation step, so check the recipient address and the label before running the skill, and test with your own address first.

Can I use a label other than needs-review?

Yes. The source says you can edit the search query to match your own label. Change the label:needs-review part of the list command to your label name.

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 label Gmail messages for follow-up and want them passed to one colleague or supervisor, and developers who want a scriptable example of combining the gws CLI with Gmail. Choose something else if you need a preview before sending, if you handle confidential or personal mail, or if you cannot install and authenticate the gws CLI.

Download the skill