add-account-negative-keywords
Skill72 starsChanged 4 months agoMITView on GitHub
Add account-level negative keywords (Admin → Account Settings → Negative Keywords) to Google Ads accounts using the 3-step SharedSet approach. Auto-invoke when user says "add account negatives", "add account-level negatives", "set up account negative keywords for [account(s)]", or "roll the negative-list baseline to [accounts]". Supports single-account and bulk-portfolio operations.
- Installs packages
In this repository41 other files it gives its agents.
- account-diagnosticSkill
- ad-copy-generation-frameworkSkill
- ad-copy-verification-standardSkill
- ads-checkerSkill
- budget-guardianSkill
- budget-recommendation-calculatorSkill
- change-history-checkerSkill
- client-communication-standardsSkill
- competitor-analysis-v2Skill
- conversion-tracking-healthSkill
- dgen-automation-disableSkill
- fair-housing-complianceSkill
- ga4-campaign-cross-referenceSkill
- ga4-cross-analysisSkill
- ga4-lead-quality-investigationSkill
- gaql-query-patternsSkill
- geo-conflict-analyzerSkill
- google-ads-api-setupSkill
- google-ads-querySkill
- google-ads-samplesSkill
- impression-share-diagnosticsSkill
- investigation-methodologySkill
- lead-quality-pattern-analysisSkill
- lead-quality-recommendation-prioritizationSkill
- markdown-to-sheets-presenterSkill
- mcc-hack-auditSkill
- mutation-safetySkill
- neg-conflict-finderSkill
- non-serving-keyword-scannerSkill
- pmax-asset-automationSkill
- pmax-builderSkill
- portfolio-health-prioritizationSkill
- portfolio-pacing-rulesSkill
- rsa-bulk-editSkill
- rsa-refreshSkill
- rsa-single-accountSkill
- shared-budget-updaterSkill
- sqr-classifierSkill
- sqr-pipelineSkill
- underspending-investigationSkill
- youtube-placement-auditSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Delete or detach anything — no keyword removals, no SharedSet deletion, no list detachment.
- Very specific: line 23
Add campaign-level negatives — that altitude belongs to sqr-pipeline (query-evidence negatives) or your campaign build.
- Distinctive: line 27
Verify which set an attachment points to — the API can't read that back (quirk table in the contract).
- Distinctive: line 47
If a set already exists for an account, only Step 2 runs — the skill adds just the missing keywords to the existing set.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add Account-Level Negative Keywords
Purpose: Roll a curated baseline of account-level negative keywords (the ones in Admin → Account Settings → Negative Keywords) across one or many Google Ads accounts, using the confirmed 3-step SharedSet approach.
Type: MUTATION skill. This writes to live accounts. The
mutation-safety two-step protocol is not a step in this
workflow — it is the workflow: dry-run preview → human reads the plan → approval code
generated → human gives the go → execution. Never chain code generation and execution
in a single action, and never skip the preview read.
This skill deliberately does NOT:
- Delete or detach anything — no keyword removals, no SharedSet deletion, no list detachment. Removals are a separate, explicitly-gated act you perform outside this skill (UI or a dedicated script you review on its own).
- Add campaign-level negatives — that altitude belongs to
sqr-pipeline(query-evidence negatives) or your campaign build. - Choose your baseline for you — the shipped sample is a starting point; curation
against your portfolio (
rules.md) is your judgment call. - Verify which set an attachment points to — the API can't read that back (quirk table in the contract); final confirmation is always the UI.
- Analyze keyword performance — no metrics are pulled anywhere in this skill.
Background — Why 3 Steps, Not 2
Account-level negatives are backed by a SharedSet of type
ACCOUNT_LEVEL_NEGATIVE_KEYWORDS. Most external guidance describes a 2-step setup that
appears to work in the API and even renders in the UI, but leaves the data model
fragile. The correct, confirmed pattern is 3 steps:
Step 1: Create SharedSet (type=ACCOUNT_LEVEL_NEGATIVE_KEYWORDS)
Step 2: Add keywords as SharedCriterion entries (PHRASE match, batched up to 1000)
Step 3: Create CustomerNegativeCriterion with negative_keyword_list.shared_set
pointing to the SharedSet ← the step most guides missIf a set already exists for an account, only Step 2 runs — the skill adds just the
missing keywords to the existing set. Re-running against a compliant portfolio is a safe
no-op. One honest limit to know: the attachment (Step 3) is created only when the skill
builds the set itself — a pre-existing set that was never attached stays unattached, and
only the session JSON tells you (references/mutation-contract.md § Categorization).
Per-Account State Categorization
For each target account, the script queries all 3 layers and routes one of three ways:
| State | Path | Mutations |
| NO_SET | Full 3-step setup | 1 SharedSet + N SharedCriteria + 1 CustomerNegativeCriterion |
| PARTIAL | Step 2 only | M SharedCriteria (only the keywords not already in the set) |
| COMPLIANT | Skip | None |
A Layer N query error: line above a categorization invalidates it — see rules.md
invariant 5 before trusting any preview that printed one.
The Two-Step Mutation Flow
Step 1 — Dry-run preview (default; mutates nothing, writes nothing)
# Single account by name
python scripts/add_account_negative_keywords.py "Example Account"
# Multiple accounts (comma-separated names or CIDs)
python scripts/add_account_negative_keywords.py "Example Account, 1234567890, Another Account"
# All accounts in a portfolio (resolved via your accounts.json)
python scripts/add_account_negative_keywords.py --portfolio my-portfolioOutput: per-account state query, categorization (NO_SET / PARTIAL / COMPLIANT), the
summary table with the Add column, and total mutation counts. Read it. The
curation and conflict checks in rules.md happen before or alongside this step.
Step 2 — Generate approval code
python scripts/add_account_negative_keywords.py "Example Account" --executeRe-queries state fresh, prints the same preview, generates a unique APPROVE-XXXXXXXX
code, and snapshots the resolved plan to a session JSON. Accounts that became compliant
since your dry-run drop out of the fresh plan.
Step 3 — Execute with approval code
python scripts/add_account_negative_keywords.py "Example Account" --execute --approval-code APPROVE-XXXXXXXXExecutes the saved session plan (the CLI account list is re-validated but the snapshot governs — see the contract), skips COMPLIANT accounts, logs every per-account result, and continues past per-account failures.
CLI Reference
| Flag | Default | Purpose |
accounts (positional) | — | Comma-separated names or CIDs (optional if using --portfolio) |
--portfolio NAME | — | Resolve all accounts in a portfolio from accounts.json (combines with positional) |
--keywords-file PATH | sample_baseline_keywords.txt | Baseline list, one per line. Bare-name default resolves against your working directory first, then falls back to the script's own folder — which is where the shipped sample lives (scripts/sample_baseline_keywords.txt). Details in the contract. |
--set-name NAME | "Account Negative Keywords" | Name for newly created sets only — delta adds go to whichever ENABLED account-level set already exists |
--exclude-cid CID | — | Skip a specific CID (repeatable) |
--execute | off | Generate approval code + save session (without this, the script is dry-run) |
--approval-code APPROVE-XXX | — | Execute the saved session for the given code |
--accounts-json PATH | accounts.json (current dir) | Path to your accounts.json |
--log-sheet-id ID | (off) | Optional Google Sheet ID for central mutation log |
--credentials PATH | google-ads.yaml | Google Ads API credentials |
--log-dir / --session-dir | skill folder's logs/ and sessions/ | Runtime output locations (derived from the script's own path, not your cwd) |
accounts.json Format
The skill resolves account names → CIDs via a local accounts.json you maintain:
{
"accounts": {
"example-account": {
"name": "Example Account",
"id": "1234567890",
"portfolio": "my-portfolio",
"aliases": ["EA", "Example"]
}
}
}Pass a name, an alias, or a raw CID. Name matching falls through to substring, and
unknown CIDs pass through as raw targets — the resolution ladder and its traps are in
the contract; read the preview's resolved-account lines, not just the totals.
Files in This Skill
| File | Role |
SKILL.md | This workflow — identity, flow, routing |
rules.md | Judgment layer: baseline curation, account-vs-campaign altitude, conflict awareness, false alarms |
examples.md | Three worked reads, including the two dry-run reads that prevent bad executions |
references/mutation-contract.md | Line-derived script mechanics: the three passes, resolution ladders, state/categorization semantics, logging, console anatomy, API quirks |
scripts/add_account_negative_keywords.py | The tool — all three passes |
scripts/sample_baseline_keywords.txt | Shipped 131-row property-management baseline (curate before use) |
logs/, sessions/ (runtime, created on demand) | JSONL audit trail; approval-code-keyed plan snapshots. Contain account names + CIDs — keep out of version control |
After a Run
- Dry-runs leave no trace — nothing on disk, nothing mutated.
- Code generation leaves one file:
sessions/account_negs_APPROVE-XXXXXXXX.json(the plan snapshot, including each account'scnc_attached— the only place that surfaces). - Execution appends one JSONL row per account to
logs/account_negs_mutations.jsonl(timestamp, account, CID, action, details, success, error, approval code) — your audit trail — plus optional Sheet rows. - Always finish in the UI: Admin → Account Settings → Negative Keywords on at least one mutated account. The API's read-back quirks make this the only true confirmation.
When to Load Other Skills
| Load | When |
mutation-safety | Before any --execute — this skill implements its Rule 1 two-step approval protocol (preview/approve/execute); the protocol rules live there |
neg-conflict-finder | After every roll (and before, if you suspect existing conflicts) — finds negatives silently blocking positives at every level |
sqr-pipeline | When the ask is query-evidence negatives ("negate these search terms") — that's campaign-level with its own review gate, not baseline material |
google-ads-query | Pre-flight: pull an account's positive keywords to grep against the baseline before the first roll |
fair-housing-compliance | PM portfolios: before deciding baseline rows touching age, family status, or income |
dgen-automation-disable | Same preview/execute mutation pattern in a different domain — useful as a second reference implementation |
google-ads-api-setup | First-time credential setup (google-ads.yaml) |
Prerequisites
- Google Ads API credentials —
google-ads.yaml(seegoogle-ads-api-setup) - Python:
pip install google-ads google-auth google-api-python-client pyyaml - An
accounts.jsonmapping names → CIDs (or pass CIDs directly) - A curated baseline keyword list (the skill ships a generic property-management
sample; curate per
rules.md, replace with your own) - For
--log-sheet-id: the refresh token ingoogle-ads.yamlmust include thehttps://www.googleapis.com/auth/spreadsheetsscope
Installation
mkdir -p .claude/skills/add-account-negative-keywords/scripts \
.claude/skills/add-account-negative-keywords/references
for f in SKILL.md README.md rules.md examples.md references/mutation-contract.md \
scripts/add_account_negative_keywords.py scripts/sample_baseline_keywords.txt; do
curl -o ".claude/skills/add-account-negative-keywords/$f" \
"https://raw.githubusercontent.com/fourteenwm/ppc-ai-skills/main/add-account-negative-keywords/$f"
doneKnown API Quirks
Four documented-but-easy-to-trip-on API behaviors (zero member counts, empty
attachment read-back, the id field name) shape how this script verifies its own
work. The full quirk table — and how the script responds to each — lives in
references/mutation-contract.md § The API quirks this script is built around.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

