Guide · Agent skill
How to use the Gmail Message Reader agent skill (gws-gmail-read)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-gmail-read skill lets an AI agent open one specific Gmail message by its ID and pull out its body, and optionally its From, To, Subject and Date headers. It is for people who want an agent to summarise or work with a known email, and for developers who script Gmail lookups through the gws command-line tool. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check for safety.
Gmail Message Readergoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws. Install the gws command-line tool so that gws runs from your terminal.
- 2Configure Google authentication. Set up Google authentication for gws as described in the gws-shared skill.
- 3Generate shared skills if needed. If the gws-shared skill is missing, run gws generate-skills.
- 4Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 5Find the message ID. Get the ID of the Gmail message you want to read, since the skill requires it.
- 6Ask the agent in plain language. Request the message by ID, for example asking for a summary or the headers.
What is an agent skill?
An agent skill is a folder containing a SKILL.md file. The file tells an AI agent when a capability applies and how to use it. Once a skill is installed, the agent can load it when your request matches the skill's description.
What does the gws-gmail-read skill make the agent do?
This skill reads a single Gmail message. It runs the gws command-line tool with the message ID you provide and returns the text body, or the HTML body if asked. It can also include the From, To, Subject and Date headers. The agent can then summarise the message or extract details from it without you copying and pasting the email.
The skill only covers reading. It does not send, delete or organise email. For those tasks, the source points to the broader gws-gmail skill.
- Reads one message by its Gmail message ID (the --id flag is required).
- Returns plain text by default, or HTML with --html.
- Adds From, To, Subject and Date headers with --headers.
- Outputs text or JSON with --format.
What do you need before installing?
The skill requires the gws command-line tool (the googleworkspace CLI). It also requires Google authentication configured for gws, which is described in the gws-shared skill. The skill's SKILL.md says that if the gws-shared skill is missing, you can run gws generate-skills to create it.
- The gws command-line tool installed and available on your path.
- Google authentication configured for gws, as described in the gws-shared skill.
- The gws-shared skill present; if it is missing, run gws generate-skills.
gws generate-skillsHow do you install the skill?
Download the ZIP from the skill page on this site. The package contains one file, SKILL.md. Unzip it so that the skill folder sits in one of these locations:
- Personal skills: ~/.claude/skills/ on your computer.
- Project skills: the .claude/skills/ folder inside a specific project.
- Claude apps: upload the ZIP under Settings → Capabilities → Skills.
How do you trigger the skill with a natural request?
You do not need to type the command yourself. Ask the agent in plain language and include the Gmail message ID. The agent matches your request to this skill's description, which covers reading a message and extracting its body or headers.
Make sure the message ID is in your request, because the skill requires --id and does not search your inbox.
- "Read Gmail message 18f1a2b3c4d and summarise it."
- "Pull the From, Subject and Date headers from Gmail message 18f1a2b3c4d."
- "Get the HTML body of Gmail message 18f1a2b3c4d."
What commands does the skill run?
The skill uses gws gmail +read. The basic form takes a message ID. The source shows these examples, which you can also run directly to check your setup.
- --headers adds From, To, Subject and Date to the output.
- --format json returns JSON, which you can pipe into tools such as jq.
- --dry-run shows the request that would be sent without running it.
- --html returns the HTML body instead of plain text.
gws gmail +read --id 18f1a2b3c4d
gws gmail +read --id 18f1a2b3c4d --headers
gws gmail +read --id 18f1a2b3c4d --format json | jq '.body'What should you know about safety?
This skill runs scripts and uses the network. It sends requests to Gmail through the gws tool, using the Google authentication you have configured. Read the security rules in the gws-shared skill before use, since they cover auth and global flags.
Use --dry-run first if you want to see the request before it runs. Because the skill only reads, it will not send or change your email, but it still reads message contents, so only use it on accounts and messages you are allowed to access.
- The skill runs scripts and makes network requests.
- Authentication is handled by the gws setup described in gws-shared.
- Use --dry-run to preview the request.
What people use it for
- Summarising a long email thread message you already have the ID for.
- Pulling the From, Subject and Date headers from a specific message for a record.
- Extracting the HTML body of a newsletter or receipt for further processing.
- Piping gws gmail +read output in JSON into jq in a shell script.
Frequently asked questions
How do I install the gws-gmail-read skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What does the gws-gmail-read skill require?
It requires the gws command-line tool and Google authentication configured for gws, described in the gws-shared skill. If gws-shared is missing, the source says to run gws generate-skills.
Is the gws-gmail-read skill free?
The source material for this skill does not state pricing or licence terms beyond its Apache-2.0 licence, so check the repository's licence for the full terms.
Can this skill send or delete emails?
No. The skill only reads a message. For sending, deleting or organising email, the source points to the broader gws-gmail skill.
Can I search my inbox with this skill?
No. The skill requires a Gmail message ID through the --id flag and does not search the whole inbox.
What should I do if the skill does not work?
Check that the gws tool is installed, that Google authentication is configured as described in gws-shared, and that the gws-shared skill exists (run gws generate-skills if it does not). Use --dry-run to see the request that would be sent.
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 an agent to read and summarise a Gmail message whose ID you already have, or if you script Gmail lookups with gws and jq. Pick the broader gws-gmail skill if you need to send, delete or organise email, or pick another tool if you need to search your inbox without knowing message IDs.
Download the skill