Label and Archive Gmail Threads with Claude Code (gws recipe)

Has your assistant find Gmail messages by search, apply a label and archive them to clear your inbox, using the gws command line.

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

This is a three-step recipe from the googleworkspace/cli repo. It searches Gmail with a query, adds a label to each match and removes the INBOX label so the message is archived.

It loads gws-gmail first and runs the gws program for every step. The sender address, message ID and label ID in the recipe are placeholders.

Steps 2 and 3 change one message at a time by message ID, so a search with many matches means the assistant repeats both steps for each. The label ID must already exist, because the recipe never creates a label. It has no filter step, so it only touches messages that already match your search.

Good for

People who want routine notification emails sorted and out of the inbox
People whose AI assistant can already run terminal commands and who use the gws command line

Install recipe-label-and-archive-emails

Claude Code

Copy this prompt.

Install the recipe-label-and-archive-emails skill in Claude Code. Run this command:

npx skills add https://github.com/googleworkspace/cli --skill recipe-label-and-archive-emails --skill gws-gmail --skill gws-shared

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.

This installs 3 skills: the recipe, the gws skills it loads (gws-gmail) and gws-shared, which those skills tell the agent to read for sign-in and safety rules. The skills only wrap the gws program, so install gws first and sign in once with gws auth login. The README says an unverified Google app limits consent to about 25 scopes, so choose only the services you need when you sign in.

From the vendor's docs. Source.

What's in the skill

When it loads

Apply Gmail labels to matching messages and archive them to keep your inbox clean.

Sections in SKILL.md

Steps

Key facts

Author: googleworkspace (GitHub organization)
License: Apache-2.0
Installs on skills.sh: 30,728 (Nov 2, 2026)
GitHub stars: 32,038 for the whole repo (Nov 2, 2026)
Status: Not an officially supported Google product
What installs: 1 file (SKILL.md). It tells the agent to load gws-gmail first.
Needs: The gws program on your PATH, plus a Google sign-in
Last commit: Oct 30, 2026 (repo)

What it includes

Lists messages that match a Gmail search query
Runs a messages list with a query such as from:notifications@service.com and prints a table.
Try: “Find all emails from notifications@service.com.”
Network · Search for matching emails
Adds a label to a message by ID
Runs a messages modify with addLabelIds for the label ID you give.
Try: “Label those emails Notifications.”
Write · Apply a label
Removes the INBOX label from a message
Runs a messages modify with removeLabelIds set to INBOX, which takes the message out of the inbox.
Try: “Archive those emails.”
Write · Archive

From the official docs

Permissions

Medium risk

The assistant can search your Gmail, add labels and move matching messages out of the inbox. Test the search query before it changes anything.

What it can do

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

Watch out for

It changes labels on your Gmail messages
Steps 2 and 3 add a label and remove the INBOX label on each matching message. Check the search query first so it matches only what you mean. github.com
Email details pass through your assistant's provider
The search step lists matching messages for the assistant to read. Use a narrow query. github.com
Needs the gws program and a Google sign-in first
The skill only wraps the gws command line. Install gws and run its sign-in before the first use, as the README describes. github.com

Technical details

Turning on read-only	The skill has no read-only switch. gws-shared tells the agent to confirm write and delete commands with you and to prefer --dry-run for destructive operations. You can also sign in with only the services you need.
Talks to	Google Workspace APIs, through the gws program
Sign-in and keys	gws keeps your Google sign-in encrypted on your machine, with the key in your operating system keyring, per the README.

Questions

What does the recipe-label-and-archive-emails skill do?

It tells your assistant how to find Gmail messages, label them and archive them. All steps run through the gws command line.

How do I install it?

Use the install box above. It installs this recipe, the gws skills it loads and gws-shared. The gws program itself is a separate install, and you sign in to Google once before the first run.

Do I need an API key?

No key is named in the skill. You need the gws program and a Google account with access to Google Workspace. The README says gws needs a Google Cloud project for OAuth sign-in credentials. gws auth setup creates one but requires the gcloud CLI, so without gcloud you set up OAuth by hand in the Cloud Console.

Does it work in the Claude app or ChatGPT?

The repo documents no route for them. The skill's steps are gws shell commands, so you need an assistant that can run commands on your computer, such as a coding agent.

Does it create the label or a filter?

No. The label ID in step 2 is a placeholder for a label you already have. recipe-create-gmail-filter is the recipe that creates a label and a filter for incoming mail.

Does it delete emails?

The recipe lists no delete step. Step 3 removes the INBOX label so the message is archived. The assistant could still run other gws commands if you ask for them.

Is it safe?

It changes labels on real messages and shows message details to your assistant. Try it on one narrow search first. The skill bundles no scripts of its own.

Is this an official Google skill?

No. The README says gws is not an officially supported Google product, although the repo sits under the googleworkspace GitHub organization.

How is it different from the other Gmail recipes?

It tidies mail that is already in your inbox. recipe-create-gmail-filter creates a label and a filter that labels and archives future matching mail. recipe-forward-labeled-emails finds messages by label and forwards them. recipe-save-email-attachments saves attachments to Drive. This one only adds a label and removes INBOX.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/recipe-label-and-archive-emails

googleworkspace/cli skills.sh

Sources

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

Show all 10

googleworkspace/cli README · github.com
recipe-label-and-archive-emails SKILL.md · github.com
gws-drive SKILL.md · github.com
skills CLI commands · github.com
recipe-create-gmail-filter SKILL.md · github.com
recipe-forward-labeled-emails SKILL.md · github.com
recipe-save-email-attachments SKILL.md · github.com
googleworkspace/cli LICENSE · github.com
recipe-label-and-archive-emails on skills.sh · skills.sh
gws-shared SKILL.md · github.com