How to use the Gmail Send Email agent skill (gws-gmail-send)

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. This skill's description is "Gmail: Send an email." It contains no logic of its own; the sending is done by the gws command-line tool.

When the skill is active and you ask the agent to email someone, the agent can compose the message with recipients, subject, body, CC and BCC, attachments, and HTML formatting. It can also save the message as a draft instead of sending it.

• Sets recipients (--to), subject (--subject) and body (--body), all required
• Adds CC and BCC recipients
• Chooses a send-as alias as the sender (--from)
• Attaches one or more files, up to 25MB total
• Formats the body as HTML (--html)
• Saves a draft instead of sending (--draft)

What do you need before installing?

The skill is only instructions. It cannot send mail unless the gws tool is installed and authenticated with your Google account. The skill's metadata lists gws as a required binary.

The skill also points to a shared skill, gws-shared, which covers authentication, global flags and security rules. If that shared skill is missing, the source says to run gws generate-skills to create it.

• The gws command-line tool (googleworkspace CLI), installed and on your path
• Your Google Workspace or Gmail account signed in through gws
• The gws-shared skill present, or created with gws generate-skills

How do you install the skill?

Download the ZIP from this page and unzip it. The skill folder contains SKILL.md. Put the folder in one of these locations, depending on how you want to use it.

For a personal skill available across your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/gws-gmail-send/
• Project only: .claude/skills/gws-gmail-send/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

How do you ask the agent to send an email?

You do not need to type the command yourself. Describe what you want in plain language, naming the recipient, subject and message. Mention attachments by file name if you have them, and say whether you want a draft. The agent should confirm the details with you before running the write command.

If you ask for something vague, such as "email Alice," expect the agent to ask for the subject, body or other missing details. Give the sender alias explicitly if you use one, since the skill can use --from for send-as addresses.

• "Email alice@example.com with the subject Hello and say hi from me."
• "Send bob@example.com a copy of report.pdf with the subject Q3 report."
• "Save a draft to alice@example.com about Friday's meeting, don't send it."
• "Send this from my alias alias@example.com, not my main address."

What does the underlying command look like?

The skill uses this basic form. The agent fills in the values from your request. The flags below are the ones in the skill's documentation.

--to takes one or more comma-separated addresses. --cc and --bcc work the same way. --attach or -a can be repeated for multiple files. --dry-run shows the request that would be sent without executing it, which is useful for checking before you send.

• --to, --subject and --body are required
• --from, --attach, --cc, --bcc, --html, --dry-run and --draft are optional
• Use --html only with fragment tags such as <p>, <b>, <a> and <br>; no <html> or <body> wrapper is needed

What safety steps should you follow?

The skill is marked as a write command, and its instructions tell the agent to confirm with you before executing it. Keep that confirmation step. Sent email cannot be recalled, so review the recipients, subject, body and attachments before you approve.

The skill runs scripts and uses the network, because the gws tool sends requests to Google. Authentication and security rules are described in the gws-shared skill, so read that before using the skill with a real account. Use --dry-run or --draft when you want to check a message first.

Do not use this skill for bulk or unsolicited mass mailing. The source says the command is not designed for that and that it may breach Gmail policies.

• Review every recipient, especially CC and BCC, before confirming
• Use --draft for anything sensitive so you can send it yourself later
• Use --dry-run to see the request without sending
• Check attachment names and total size (25MB limit)