Guide · Agent skill
How to use the Create Gmail Filter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains the Create Gmail Filter agent skill, named recipe-create-gmail-filter, and how to install and use it. An agent skill is a folder of instructions that an AI agent such as Claude loads when a request matches the skill's purpose. After reading, you will know what the skill does, how to add it, how to phrase a request, and what to check before letting it change your Gmail settings.
Create Gmail Filtergoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install the gws tool. Install the gws command-line tool and connect it to your Google account with authorised Gmail access. The skill cannot run without it.
- 2Load the gws-gmail skill. Make sure the gws-gmail skill is available, since this recipe lists it as a prerequisite.
- 3Add this skill. Download the ZIP from this page, unzip it, and place the folder in ~/.claude/skills/ or a project's .claude/skills/. Or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Ask in plain language. Describe the email you want sorted, for example mail from a specific sender getting a label and skipping the inbox.
- 5Review the commands. Check the gws commands the agent proposes before approving them, since they change live Gmail settings.
- 6Verify the filter. Ask the agent to list filters, or check the list output, to confirm the new rule was saved.
What the skill makes the agent do
Once installed, the agent can create rules in your Gmail account that automatically apply labels, star messages, or move incoming messages out of the inbox based on criteria such as the sender. The skill walks the agent through four steps: list your existing labels, create a new label if needed, create the filter, and then list filters to confirm it was saved.
The agent does this by issuing commands through the gws command-line tool. The skill cannot work without gws installed and connected to your Google account.
- List existing labels
- Create a new label if needed
- Create the filter
- List filters to verify the new one was saved
Install the skill
Download the ZIP from the skill's page on this site and unzip it. The skill is a folder containing SKILL.md. Put that folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to limit it to that project.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
Before the skill runs, install the gws command-line tool and load the gws-gmail skill, which this recipe lists as a prerequisite. You also need authorised access to your Google account for Gmail through gws.
- Copy to ~/.claude/skills/ for personal use
- Copy to a project's .claude/skills/ for project use
- Or upload via Settings → Capabilities → Skills in the Claude apps
Trigger the skill with natural requests
You do not need to name the skill. Describe the outcome you want in plain language, such as sorting a type of email into a label. The agent should match the request to this skill when it involves creating a Gmail filter.
Name the sender or the sender address when you can, because the example in the skill matches on sender. Say whether the messages should be labelled, starred, or moved out of the inbox.
- "Create a Gmail filter so emails from receipts@example.com get a Receipts label and skip the inbox."
- "Star every newsletter from news@example.com as it arrives."
- "Check my existing Gmail filters and tell me which ones move mail out of the inbox."
Example: the command sequence behind a filter
The skill's example creates a label called Receipts, then creates a filter that matches mail from receipts@example.com, adds the new label, and removes the INBOX label. The final step lists filters so you can confirm the rule exists. The label ID in the filter command is a placeholder that the agent replaces with the ID returned when the label was created or found.
These are the commands the skill lists. Read them before approving a run.
gws gmail users labels list --params '{"userId": "me"}' --format table
gws gmail users labels create --params '{"userId": "me"}' --json '{"name": "Receipts"}'
gws gmail users settings filters create --params '{"userId": "me"}' --json '{"criteria": {"from": "receipts@example.com"}, "action": {"addLabelIds": ["LABEL_ID"], "removeLabelIds": ["INBOX"]}}'
gws gmail users settings filters list --params '{"userId": "me"}' --format tableSafety notes: scripts and network access
This skill runs scripts and uses the network. It changes live settings in your Gmail account. The source notes that changes like these are hard to undo casually, so review the proposed commands before the agent runs them, especially the filter creation step.
The skill's example matches only on sender. The source gives limited guidance on other filter criteria, so for anything beyond a sender match, check the resulting filter in Gmail or with the list command.
- Review each proposed gws command before approving it
- Check the filter list after creation to confirm the rule is what you intended
- Use a test sender address first if you are unsure
Tips for good results
The skill suits recurring mail such as receipts or newsletters. Ask for the filter to be verified at the end so the agent runs the list step. If you already use gws for other Gmail tasks, the same setup covers this skill.
Keep requests specific. A sender address and a clear action give the agent enough to build the filter.
- Use the list step to audit existing filters without opening Gmail settings
- Give one sender and one action per request to keep the result easy to check
What people use it for
- Sorting recurring receipts from a shop or service into a Receipts label
- Starring newsletters from a specific sender so they stand out
- Moving automated notifications out of the inbox while keeping them labelled
- Auditing existing Gmail filters by listing them in a table
Frequently asked questions
How do I install the Create Gmail Filter agent skill?
Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills. You also need the gws tool and the gws-gmail skill.
What do I need before this skill works?
You need the gws command-line tool installed, authorised access to your Google account for Gmail through gws, and the gws-gmail skill loaded. The skill cannot work without gws.
Is the Create Gmail Filter skill free?
The source is licensed under Apache-2.0. The source does not state pricing for the skill, so check the license file in the repository for terms.
Can the skill create filters on criteria other than sender?
The example in the skill matches only on sender. The source gives limited guidance on other criteria, so review any filter you create beyond a sender match in Gmail.
Will this skill change my Gmail without asking?
The agent runs gws commands that change live Gmail settings. Review the proposed commands before approving them, because filter changes are hard to undo casually.
What are alternatives to this skill for Gmail filters?
You can create filters by hand in Gmail settings. The source does not compare this skill with other tools, so judge the alternatives yourself.
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
This skill suits people who already use the gws tool and want an agent to create or audit Gmail filters for recurring mail such as receipts or newsletters. It is not a good fit if you cannot install and authorise gws, or if you need complex filter criteria, since the skill gives limited guidance beyond sender matches. Review each change before approving it.
Download the skill