Guide · Agent skill
How to use the Label and Archive Gmail agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Label and Archive Gmail skill teaches an AI agent a short, repeatable recipe: find Gmail messages that match a search, add a label to them, and remove them from your inbox. The messages stay in your account, just out of the inbox view. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before letting it make bulk changes.
Label and Archive Gmailgoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws and authenticate. Set up the Google Workspace CLI (gws) and sign in with the Google account you want to manage. The recipe cannot run without it.
- 2Install the gws-gmail skill. Make sure the companion gws-gmail skill is available, since this recipe depends on it.
- 3Download and unzip this skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 4Ask for a narrow change. Request labelling for one sender or pattern, naming the label you want.
- 5Review the matches. Check the messages the agent finds before it applies any changes.
- 6Confirm the archive. Verify that matched messages now have your label and are no longer in the inbox.
What the skill makes the agent do
The skill is a recipe, not a standalone app. It tells the agent how to tidy Gmail in three steps: search your mailbox for messages matching a query (for example, mail from one sender), apply a chosen label to those messages, and remove the INBOX label so they leave your inbox.
The agent does this by issuing commands through the Google Workspace command-line tool gws. The recipe depends on the companion gws-gmail skill for the underlying Gmail details.
- Searches messages with a Gmail query such as from:notifications@service.com
- Adds a label to matching messages
- Removes the INBOX label so the messages are archived
What you need before installing
The recipe cannot run without the gws tool. You also need an authenticated Google account with Gmail access via gws, and the gws-gmail skill loaded alongside this one. The skill is for Gmail accounts only.
- gws command-line tool (Google Workspace CLI)
- gws-gmail skill
- An authenticated Google account with Gmail access via gws
How to install the skill
Download the ZIP file from this page. Then choose one of the following options.
For a personal install across all your projects, unzip the file into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with natural requests
You do not need to type the skill name. Describe the outcome you want in plain language and name the sender or pattern. The agent should search first and show you what matches before changing anything, so review the matches.
Good requests name a clear sender or pattern and a label, for example: label all mail from notifications@service.com as Automated and archive it. Keep the first request narrow, then widen it once you have seen the results.
- Label mail from notifications@service.com as Automated and archive it
- Archive newsletters from a specific sender under a Newsletters label
- Show me what matches from:billing@example.com before you change anything
The underlying commands
These are the three commands the recipe is built on. You do not need to run them yourself, but reading them shows exactly what will happen. MESSAGE_ID and LABEL_ID are placeholders that the agent fills in.
- Search: lists messages matching a query
- Apply label: adds the label ID to a message
- Archive: removes the INBOX label from a message
gws gmail users messages list --params '{"userId": "me", "q": "from:notifications@service.com"}' --format tableSafety notes: scripts and network access
This skill does not run scripts. It does use the network, because each command talks to Gmail through gws. It only relabels and archives. It does not permanently delete or trash email.
A broad query can still move many messages out of view, so check the matches first. Only use this skill with an account you have authenticated with gws and are comfortable changing.
- Runs scripts: no
- Uses network: yes, to reach Gmail through gws
- Does not delete or trash messages
- Review search results before bulk changes
Tips for getting good results
Start with a narrow query, such as one sender, and confirm the list looks right. Then broaden it. Use labels you will recognise later, because archived mail is found by label rather than in the inbox.
- Test with one sender before a broad pattern
- Use descriptive label names
- Check that gws and gws-gmail are both set up before you start
What people use it for
- Keep automated service notifications out of the inbox under a label such as Automated
- Archive newsletters from a specific sender while keeping them searchable
- Sort recurring billing or receipt emails under a finance label
Frequently asked questions
How do I install the Label and Archive Gmail skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need before I can use this skill?
You need the gws command-line tool (Google Workspace CLI), the gws-gmail skill, and a Google account authenticated with Gmail access via gws. Without gws the recipe cannot run.
Does this skill delete my emails?
No. The recipe only applies a label and removes the INBOX label, so messages stay in your account. A broad query can still hide many messages from your inbox, so check the matches first.
Is this skill free to use?
The source does not state pricing or licence terms beyond the licence listed for this item, which is Apache-2.0. Check the repository's licence file for the terms that apply.
Does it work with non-Gmail accounts?
No. The skill is built around Gmail through the gws tool, and the recipe cannot run without gws set up with a Google account.
What are alternatives if this skill does not fit my needs?
If you do not use gws or Gmail, this skill will not help. You would need a different tool or a manual approach for your mail provider. The source does not compare it with other tools.
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
Use this skill if you already have gws installed and authenticated, and you want an agent to sort recurring Gmail notifications or newsletters under a label and out of your inbox. Pick something else if you need to delete or trash mail, use a non-Gmail account, or do not want to set up the gws tool.
Download the skill