recipe-create-gmail-filter Skill: Create a Gmail Filter and Label

Creates a Gmail label and a filter that labels, stars or categorizes incoming messages automatically.

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

recipe-create-gmail-filter is a four-step recipe for Gmail filters: list your labels, create a new one, create a filter that applies it, then list the filters to check. It uses the gws program through the gws-gmail service skill. The example filters mail from receipts@example.com into a Receipts label and removes it from the inbox. A filter keeps acting on future mail, so check the criteria first.

Good for

Gmail users who want incoming mail sorted without clicking through settings
Anyone tidying receipts, newsletters or alerts into labels
Claude Code or Codex users who already run the gws program

Install recipe-create-gmail-filter

Claude Code

Copy this prompt.

Install the recipe-create-gmail-filter skill in Claude Code. Run this command:

npx skills add https://github.com/googleworkspace/cli --skill recipe-create-gmail-filter --skill gws-gmail --skill gws-shared -a claude-code

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, gws installed and signed in.

Do the "First" and "Then" methods once before the skills command: they install gws and sign you in. The skills command adds 3 skills (recipe-create-gmail-filter, gws-gmail, gws-shared) because recipe-create-gmail-filter reads gws-shared first and points to the others in the set. Without gcloud, use the manual OAuth setup in the README. To limit what the sign-in grants, run gws auth login -s gmail so the consent screen lists only those services.

From the vendor's docs. Source.

What's in the skill

When it loads

Create a Gmail filter to automatically label, star, or categorize incoming messages.

Sections in SKILL.md

Steps

Key facts

Author: googleworkspace organization (repo owner)
Status: Not an officially supported Google product, per the README
License: Apache-2.0
Installs on skills.sh: 31,629 (Nov 2, 2026)
GitHub stars: 32,038 (Nov 2, 2026) (whole repo)
Last commit: Oct 30, 2026
What installs: 1 file, SKILL.md; it bundles no scripts
Needs: the gws program signed in to Google, plus gws-shared and gws-gmail
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
Documented setups: skills CLI, OpenClaw, Gemini CLI extension

What it includes

Lists your existing labels
Step 1, shown as a table.
Network · gws gmail users labels list
Creates a new label
The example creates a label named Receipts.
Write · gws gmail users labels create
Creates the filter
The example matches a sender and adds the label.
Write · gws gmail users settings filters create
Verifies the filter
Step 4, shown as a table.
Network · gws gmail users settings filters list

From the official docs

Permissions

Medium risk

It creates labels and a filter that keeps applying to future mail, and the example filter removes matching mail from your inbox. Sign in with only the services you need and read each command before you approve it.

What it can do

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

Watch out for

A filter keeps acting on future mail
The example filter takes mail out of the inbox. Check the criteria so it does not hide mail you need, and remove the filter in Gmail settings if it misfires. github.com
The project is in active development
The README says to expect breaking changes before v1.0. Re-read the install steps after you update gws. github.com

Technical details

Turning on read-only	No read-only switch in the skill. The gws-shared skill says to prefer --dry-run for destructive operations and to confirm write commands with you.
Talks to	Google Workspace APIs through gws
Sign-in and keys	gws sign-in. The README says credentials are encrypted at rest (AES-256-GCM) with the key kept in your OS keyring.
Scopes	Whatever Google services you grant when you sign in to gws

Questions

What does recipe-create-gmail-filter do?

Creates a Gmail label and a filter that labels, stars or categorizes incoming messages automatically.

How do I install recipe-create-gmail-filter in Claude Code?

Use the install box above. It adds recipe-create-gmail-filter together with gws-gmail, gws-shared in one step. You also need the gws program installed and signed in to Google first, and the box lists both steps.

Does recipe-create-gmail-filter work in the Claude app or Codex?

The install box has a Codex tab that uses the skills CLI's Codex target, but the repo README does not list Codex as a supported setup. The README documents no Claude app route, and every command runs the gws program in a terminal, so use Claude Code or another terminal agent.

Does recipe-create-gmail-filter need an API key?

No API key. It uses your Google sign-in through gws, and the README says you need a Google Cloud project for the sign-in credentials. gws auth setup can create one if you have the gcloud CLI.

Is recipe-create-gmail-filter safe?

It creates labels and a filter that keeps applying to future mail, and the example filter removes matching mail from your inbox. Check the criteria before you approve the filter step.

Can it delete mail?

The recipe creates labels and filters and lists them. Its example filter removes the inbox label from matching mail, which hides it from the inbox rather than deleting it.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/recipe-create-gmail-filter

googleworkspace/cli skills.sh

Sources

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

Show all 4

googleworkspace/cli README · github.com
skills CLI commands · github.com
recipe-create-gmail-filter SKILL.md · github.com
gws-shared SKILL.md · github.com