filter
Add or update a filters.js entry from a plain-language description ("archive the weekly digest from Acme", "label everything from my bank as Finance"). Infers the deterministic rule, states it back, c
SKILL.md.claude/skills/filter/SKILL.md
GitHubFilter (description → one deterministic rule in filters.js)
Input is a description of mail and what should happen to it. Output is a rule that is exactly
expressible in the spec, stated back to the user, landed in filters.js without duplicating
anything already there, and synced to the account.
Examples in this file are invented. The privacy rule in AGENTS.md applies to anything this skill
writes into committed files; filters.js itself is gitignored and is where real senders belong.
Procedure
0. Prefix the session title with ⏳
Read the title (mcp__ccd_session_mgmt__get_session with "self") and set it back with a ⏳
prefix, replacing any existing one. Later steps move it to 🔍, 💾 or 🚙. Never mention it. See
AGENTS.md → Repo → Session titles.
1. Pin down the message
A rule needs real header values, not the description's paraphrase of them.
- Sender address, not display name — "mail from Acme" says nothing about whether it comes from
news@acme.comornoreply@mail.acme-billing.com. - Subject as sent, if the rule is about one kind of mail from a sender that sends several.
- List-Id, if it is mailing-list mail.
If the user gave a screenshot, read it as the match skill does (step 1 there). Otherwise, or if a
value is not legible, fetch examples with the Gmail MCP: search_threads for the sender or subject
returns each hit's sender address and subject, and get_message with RAW — the only format that
carries headers — shows a List-Id. Look at several messages, not one — the family's real
variation decides the shape of the rule.
2. Infer the rule
Translate into the spec's vocabulary only (README → Spec): from (sieve glob), subject
(contiguous substring), list (List-Id substring); criteria in one condition AND, conditions in one
entry OR. Actions are fileinto destinations: a label name, archive (skip inbox), trash, neverspam (Gmail only: never send to Spam).
Choose the narrowest rule that still covers the whole family:
fromshape. Exact address for a person, or for a consumer domain (gmail.com,outlook.com).*@domainfor a company whose every sender should be treated alike.*@*.domainonly when mail genuinely arrives from rotating subdomains. Rotating local parts (no-reply-<hash>@) need a glob.- A processor address that encodes an account id is exact-address material. Payment and
notification intermediaries send every client's mail from one domain, keying the merchant in the
local part, so the address identifies the sender as precisely as its own domain would — and a
*@processorglob would sweep in every unrelated merchant the spec files elsewhere. Keep asubjectanyway: the same address carries the failure and reminder mail that must stay in the inbox, which a receipt-only fragment excludes. - Never let a
fromreduce to a bare TLD or a token so short Gmail matches half the mailbox. Short dangling glob fragments are dropped by the Gmail renderer (AGENTS.md→ What the code does), so*s@acme.commeansacme.comin Gmail. subjectonly when the sender also sends mail that must not match. It should match a kind of mail, not the message in hand, so it keeps the template's fixed wording and drops everything filled in per message: dates and times, amounts and counts, order, ticket and tracking numbers, and names — of people (the user's own included), documents, products. Strip these even when every sample agrees on one; samples from one week, or all from one colleague, share values the next message will not. Keep a value only when the description singles it out ("the digest for the Berlin team").- Stripping splits the subject into pieces, and
subjecttakes one contiguous fragment: the longest piece, trimmed to whole words, that every real subject in the family contains and the sender's other mail does not.Your March 2026 usage reportgivesusage report;Alice commented on your postgivescommented on your post. A family that varies mid-phrase needs one condition per variant. A double quote is a split point too: Gmail search has no escape for one, so the renderer refuses anysubjectthat contains it. - Test the fragment on the account:
search_threadsforfrom:<sender> subject:"<fragment>"should find this kind of mail across different dates and names, and none of the sender's other mail. - Label names must already exist on the account unless the user is asking for a new one. Compare
against labels used elsewhere in
filters.jsandlist_labels; near-identical names are a typo, not a new label (ReceiptvsReceipts).
Anything the spec cannot express — a recipient condition, "unless it mentions X", mark-as-read,
removing a label — is not a filters.js rule. Say so, and say where it would have to live (a
hand-made Proton filter, a Shortwave AI filter), rather than approximating it.
3. State the rule back
Draft the rule now; present it once step 4 has classified it, and before step 5 edits anything.
Render it with the render-filter skill, which holds the table and the sentence under it.
Change is filled on every row, from step 4's classification; Replaces on a widen or
update. A duplicate row names the existing entry's actions, not the requested ones, so a
mismatch is visible.
Name any inference the description did not force — a glob widened from one address, a subject fragment chosen from several samples, a date or name stripped from a subject, a label picked from near matches. If the description left a real choice open (which label, archive or not, whole sender or one kind of mail), ask instead of guessing, and set 🚙 first. Otherwise proceed; the statement is there so the user can object.
4. Check for duplicates and overlaps
Resolve CONFIG (AGENTS.md → Files outside git) and re-read $CONFIG/filters.js now — it
is shared across worktrees and may have changed since the session started.
Run every sample message from step 1 through the matcher:
node .claude/skills/match/match.js --from <address> --subject "<subject>" [--list <list-id>]
That covers the forward direction — existing entries that already match the mail. It does not cover
the reverse: existing narrower conditions the new rule would subsume. For that, grep the spec for
the sender's distinctive domain label (acme, not com) and read every hit.
Then classify:
| Finding | Action |
|---|---|
| An entry already matches with the same actions | Duplicate. Change nothing; tell the user which entry already does it. |
| Nothing related | Add. Append the condition to the entry with the same actions, or add a new entry if none. |
| An entry matches with different actions, and the user asked for a change | Update. Edit that condition (move it to the other entry, or change its entry's actions if it is alone there). |
| The new rule would subsume narrower conditions with the same actions | Widen. Replace them with the new condition rather than adding beside them. |
Near miss (stale sender, sibling domain) |
Update the stale condition to the sender's new address rather than adding a second one. |
| Partial overlap with different actions | Judgment — see below. |
Several entries can share one action set, and then the choice between them is organizational only:
Specs merges by action set and re-chunks, so which entry holds a condition changes only which
600-char chunk its terms land in, never the effect. Pick by the section comment above the entry —
what that group is about — and leave the rendering out of it.
Partial overlap is when some of the mail is already handled differently: the new rule is
*@acme.com → archive and an existing condition sends billing@acme.com to Finance. Gmail applies
every matching filter and they stack (label + archive both happen; trash hides mail from label
views); Proton's last conflicting fileinto wins. Work out what the overlapping mail would actually
get after the change:
- If the stacked result is plainly what the user wants (a label plus skip-inbox), proceed and say so.
- If it is plainly not (trash overlapping a label the user reads), narrow the new rule — a
subject, or exact addresses instead of a glob — and say so. - If it could go either way, ask, naming the specific mail affected and the two outcomes. Set 🚙.
Moving a condition between entries also matters when an entry's actions are shared by other conditions: never change an entry's actions to fix one sender — move that sender out.
5. Edit filters.js
Edit $CONFIG/filters.js in place (it produces no git diff). Match the file's existing style:
comment on a condition where the sender alone does not say what the mail is. Then verify by
loading, not reading:
node -e 'const f=require(process.argv[1]); console.log(f.length, f.reduce((n,e)=>n+e.conditions.length,0))' "$CONFIG/filters.js"
The condition count should move by exactly what step 4 decided. A count that moved by more than you
added is another session's edit to the shared spec, not a misfire of yours — name it and leave it
alone, per AGENTS.md → Gmail → Account and filters.
Re-run the matcher on the samples: the intended entry — and only the intended entries — should now match.
6. Sync
Follow AGENTS.md → Gmail → Account and filters, which authorizes applying a clean plan without
asking. Set 🔍, then dry-run: node src/sync.js --verbose (the spec and credentials default to
the config directory).
Audit the plan: every deleted term reappears in a created query under the same label (re-chunking),
the new terms appear under the intended label, Labels to create holds nothing unexpected, no bare
TLD. If the plan carries changes this edit does not explain, that is pending drift or another
session's edit — stop and report it rather than applying it along with yours.
A clean plan: set 💾, node src/sync.js --apply --yes, then set 🚙 or leave 💾 per
the session-title rules.
7. Report
- The rule table from step 3, updated to what was actually written — its Change column says what happened to the spec.
- Any overlap and how it resolves for the overlapping mail.
💾 Synced to gmailwhen the apply ran.
Do not mention mail already in the inbox or offer to apply the filter retroactively.