agentleFS
fourteenwmfourteenwm/ppc-ai-skills/youtube-placement-audit/SKILL.md

youtube-placement-audit

Skill72 starsChanged 4 months agoMITView on GitHub

Audit Google Ads accounts for bad YouTube placements (kids content, adult, gaming, non-English, spam) across PMAX, Demand Gen, and Display campaigns. Flags violations, writes to Google Sheets, then extracts channels for bulk negation.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    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
  1. Distinctive:

    Read the flags through rules.md's category table — the substring traps live there

    line 134
  2. Distinctive:

    Add channel URLs as placement exclusions:

    line 139
  3. Very specific:

    All four tabs carry a Run Date column — check it per tab before acting (a tab with no rows this run keeps last run's data.

    line 154

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

YouTube Placement Brand Safety Audit

Scans all accounts under your MCC for YouTube placements and flags brand safety violations, then aggregates flagged videos by channel so you can negate at the channel level instead of one video at a time. The flags are machine leads; the negate/keep calls live in rules.md, and exact script mechanics live in references/audit-contract.md.


Why This Exists

PMAX and Demand Gen campaigns serve ads on YouTube placements you never chose. Without active auditing, your ads show on kids' channels, foreign-language content, spam videos, and worse. Google doesn't give you a "block all kids content" button, so you need to find and exclude these placements yourself.

The manual way: Export placements, eyeball thousands of rows, copy URLs, add exclusions one by one.

This skill: Scan all accounts, flag violations automatically, aggregate by channel, get a clean negate list.


What this skill deliberately does NOT do

  • Never touches Google Ads state. Both scripts read the API and write a sheet; placement exclusions are applied by you in the UI or Editor.
  • Doesn't judge placements. A flag means a pattern matched (substring, case-insensitive — Toyota trips toy). The negate/keep call is rules.md's category table, not the flag itself.
  • Doesn't see foreign languages in Latin script. The non-English check reads Unicode scripts — Spanish/French/German content never flags (contract). Extend FLAGGED_KEYWORDS if that matters for your market.
  • Doesn't route flagged channels through the extractor. Channel-type placements are already channels — the extractor only processes video rows, so pull YOUTUBE_CHANNEL rows from the Bad tabs directly when building the exclusion list.
  • Audits ENABLED accounts only — paused/canceled accounts under the MCC are never scanned.

What Gets Flagged

27 keywords across 6 reason labels (full table + matching semantics: contract):

  • Kids content (15 keywords — toy, cartoon, roblox, minecraft, peppa pig…) → the biggest category and the biggest false-positive surface
  • Adult content (4) · Gaming content (3) · Spam and Spam/Clickbait (3) · Legal (2 — dui, bail bonds)
  • Null/Empty placements — blank/unnamed placements (low-quality inventory), written to the keyword tab
  • Non-English content → the Bad - YouTube - NEA tab: 24 non-Latin Unicode scripts (Cyrillic, Arabic, Hebrew, CJK, Devanagari, Thai…) — detection is per-character and script-based, and it runs only when no keyword matched

Setup

Prerequisites

  1. Google Ads API access (google-ads.yaml credential file)
  2. YouTube Data API v3 key (for channel extractor only)
  3. Python 3.10+

Install

pip install google-ads gspread google-auth google-api-python-client pyyaml

Credentials

Your google-ads.yaml needs:

client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
developer_token: YOUR_DEVELOPER_TOKEN
login_customer_id: YOUR_MCC_ID
use_proto_plus: true
youtube_api_key: YOUR_YOUTUBE_API_KEY  # only for channel extractor

Google Sheets access reuses the same OAuth credentials. Your GCP project needs the Sheets scope enabled, and the OAuth account needs edit access to the output sheet.


Usage

Step 1: Run the placement audit

# Test with 3 accounts
python scripts/youtube_placement_audit.py --mcc 1234567890 --sheet SHEET_ID --test --limit 3

# Full audit
python scripts/youtube_placement_audit.py --mcc 1234567890 --sheet SHEET_ID --force

# Filter to specific accounts
python scripts/youtube_placement_audit.py --mcc 1234567890 --sheet SHEET_ID --filter "Acme" --force

A zero-flag run writes nothing (existing tab rows persist — check Run Date), and a failed per-account query is silent: an account printing No YouTube placements against sibling accounts full of them is the false-clean tell (rules.md § triage).

Step 2: Extract channels (recommended)

# Both keyword + NEA channels
python scripts/youtube_channel_extractor.py --sheet SHEET_ID --creds google-ads.yaml --force

# Only non-English channels
python scripts/youtube_channel_extractor.py --sheet SHEET_ID --creds google-ads.yaml --nea-only --force

Step 3: Review, then negate in Google Ads

  1. Open your Google Sheet
  2. Read the flags through rules.md's category table — the substring traps live there
  3. Build the exclusion list: "Channels to Negate" tabs plus the YOUTUBE_CHANNEL rows from the Bad tabs (those bypass the extractor)
  4. Add channel URLs as placement exclusions:
    • PMAX: Campaign-level placement exclusions
    • Demand Gen / Display: Ad group or campaign exclusions

Output

Sheet TabContent
Bad - YouTubeKeyword-flagged placements (incl. Null/Empty)
Bad - YouTube - NEANon-English Alphabet placements
Channels to NegateAggregated channels from keyword flags
Channels to Negate - NEAAggregated channels from NEA flags

All four tabs carry a Run Date column — check it per tab before acting (a tab with no rows this run keeps last run's data; contract).


PMAX API Limitation

The performance_max_placement_view resource only returns impressions. Clicks, cost, and conversions show as 0 for PMAX campaigns. Full metrics are available for Display and Demand Gen. Triage PMAX rows on impressions — zeros there are the API, not evidence.


The Channel Aggregation Payoff

Flagging individual videos is step one. The channel extractor is where the real leverage is:

  • 24,000 flagged videos -> ~9,000 channels (62% reduction)
  • Each channel exclusion blocks ALL future videos from that channel
  • One monthly run keeps your placements clean

Customization

Edit FLAGGED_KEYWORDS at the top of youtube_placement_audit.py to add industry-specific terms. For example, a B2B SaaS company might add:

'free download': 'Spam',
'crack': 'Piracy',
'tutorial for kids': 'Kids content',

Custom terms inherit substring matching — crack also hits "firecracker". rules.md § customization judgment has the isolation tricks; test list changes with --test first.


Runtime

AccountsAuditChannel Extraction
10~2 min~30 sec
50~8 min~1 min
100~15 min~2 min
300+~25-30 min~4-5 min

Run monthly.


Files

FilePurpose
SKILL.mdThis file — workflow + routing
rules.mdJudgment layer: category calls, substring traps, when NOT to negate, triage order, cadence
examples.mdThree worked reads incl. the false-clean account and the Toyota trap
references/audit-contract.mdLine-derived mechanics of both scripts: taxonomy, matching, silent-swallow, tab semantics
scripts/youtube_placement_audit.pyStep 1 — scan accounts, flag, write the Bad tabs
scripts/youtube_channel_extractor.pyStep 2 — aggregate flagged videos into channels
README.mdUser-facing overview + install

After a Run

The Google Sheet is the only durable record — console output isn't persisted. Each tab's Run Date column says when it was last actually written (audit tabs: date; channel tabs: date+time). Account state never changes from running either script; if a cold session needs to know whether exclusions were applied, that evidence lives in Google Ads change history, not here.


When to Load What

MomentLoad
Reading flag output — negate/keep calls, traps, triagerules.md
Exact matching/tab/query mechanics, the silent-swallow and stale-tab trapsreferences/audit-contract.md
First read, or a portfolio that looks suspiciously cleanexamples.md
An account reads empty and you need to separate no-data from no-accessgoogle-ads-query — its errors surface loudly
This check as one slice of a full account sweepaccount-diagnostic — its placement-safety checks (37-38) route here for the full portfolio sweep
No API credentials yetgoogle-ads-api-setup
Scripting the exclusions themselves (mutation)mutation-safety — preview, approve, execute, verify

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.