Guide · Agent skill
How to use the Gmail Unread Triage agent skill (gws-gmail-triage)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Gmail Unread Triage skill (gws-gmail-triage) lets an AI agent pull a short list of your unread Gmail messages and show who sent each one, the subject and the date. It is built for people with busy inboxes who want a quick overview, and for developers who want that summary as JSON for scripts. This guide explains what an agent skill is, how to install this one, how to ask for it in plain language, and what to check for safety before you use it.
Gmail Unread Triagegoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install the gws tool. Install the gws command-line tool (Google Workspace CLI) and make sure it runs on your machine.
- 2Authenticate your Google account. Set up your Google account through gws, following the gws-shared skill for authentication.
- 3Download the skill ZIP. Download the gws-gmail-triage ZIP from our page and unzip it. It contains SKILL.md.
- 4Place the skill folder. Unzip into ~/.claude/skills/ for personal use, into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Ask for your unread summary. Request an unread inbox summary in plain language. The agent runs gws gmail +triage.
- 6Narrow the results. Ask for a limit or a Gmail search filter, which maps to the --max and --query flags.
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 when and how to perform a task. This skill, gws-gmail-triage, teaches the agent to run the gws command-line tool (the Google Workspace CLI) to show a summary of your unread Gmail.
For each message the summary shows the sender, the subject and the date. You can narrow the list with a Gmail search query, limit how many items appear, or include label names. The skill states that it is read-only and does not change your mailbox.
What you need before you install
The skill cannot run without the gws command-line tool installed and authenticated. You also need a Google account set up through gws. The skill's documentation points to the gws-shared skill for authentication, global flags and security rules. If that shared skill file is missing, the source says to run gws generate-skills to create it.
- gws command-line tool (Google Workspace CLI) installed
- An authenticated Google account set up through gws (see the gws-shared skill)
- The skill runs scripts and uses the network, so review it before installing
Install the gws-gmail-triage skill
Download the ZIP for this skill from our page and unzip it. The skill ships as a single file, SKILL.md. 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
How to trigger the skill with natural requests
You do not need to type the command yourself. Ask the agent in ordinary language, such as asking for a summary of your unread email. The skill's underlying command is gws gmail +triage, and the agent runs it for you. You can also mention limits or filters in your request, for example asking for only the five most recent unread messages from your boss, which maps to the --max and --query flags.
Command examples and flags
These are the commands listed in the skill. The flags are --max (maximum messages to show, default 20), --query (a Gmail search query, default is:unread) and --labels (include label names in output). Output defaults to a table.
gws gmail +triage
gws gmail +triage --max 5 --query 'from:boss'
gws gmail +triage --format json | jq '.[].subject'
gws gmail +triage --labelsSafety notes: scripts and network access
The skill runs scripts and uses the network, as listed on its page. It reads message metadata (sender, subject, date) from your Gmail account through the gws tool. The skill states that it is read-only and never modifies your mailbox. If you have a sensitive mailbox where the agent should not read message metadata at all, do not install this skill.
- Read-only: the skill does not send, reply, label or delete mail
- Uses the network and runs scripts, so check the SKILL.md before installing
- Authentication and security rules are described in the gws-shared skill
Tips for getting better results
Use the --query flag with Gmail search syntax to focus the list, and --max to keep the output short. If you are scripting, use --format json and pipe the output into a tool such as jq. For actions beyond reading, such as sending or organizing email, use the related gws-gmail skill instead.
- Keep the default --max of 20 for a quick scan, or lower it for a shorter list
- Add --labels when you want to see which labels each message has
- Pipe JSON output into jq when you need specific fields
What people use it for
- Get a quick morning overview of unread mail sender by sender
- Check whether anything from a specific person, using a from: query, has arrived unread
- Pipe a JSON list of unread subjects into a script for a daily digest
- Include label names to see how unread mail is currently categorised
Frequently asked questions
How do I install the gws-gmail-triage skill?
Download the ZIP from our page and unzip it. Put the folder in ~/.claude/skills/ for personal use, in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need before the skill will work?
You need the gws command-line tool (Google Workspace CLI) installed and authenticated with your Google account. The skill cannot run without it. The skill's documentation points to the gws-shared skill for setup.
Is the gws-gmail-triage skill free?
The skill is licensed under Apache-2.0. The source does not state pricing for the gws tool or any Google service, so check those separately.
Can this skill delete, send or reply to my email?
No. The skill states it is read-only and never modifies your mailbox. It only shows a summary of unread messages. For sending, replying or organising mail, use the related gws-gmail skill.
Why does the skill fail or not appear?
The source says the skill needs the gws tool installed and authenticated. If the shared gws-shared SKILL.md file is missing, run gws generate-skills to create it, as the skill's prerequisite note describes.
What is the difference between this skill and the gws-gmail skill?
gws-gmail-triage only reads a short unread summary. The related gws-gmail skill covers all send, read and manage email commands.
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 want a fast, read-only overview of unread Gmail, or want that summary as JSON for scripts, and you already use or are willing to set up the gws tool. Skip it if you need to send, reply to or organise email, if you have not installed and authenticated gws, or if you do not want an agent reading message metadata from your mailbox.
Download the skill