Snitch Adsready

snitch-adsready

The ads-ready.sh beside this SKILL.md exposes thin tools. Read tools emit JSON on stdout; doctor and the proposal-generating fix tools emit status badges instead. Run bash "${CLAUDE_SKILL_DIR}/ads-ready.sh" help for the full surface.

Ten platforms are tool-backed: Google, Meta, Microsoft, LinkedIn, TikTok, X, Pinterest, Reddit, Snapchat, Apple. One more — ChatGPT ads — is presence-only: no pixel exists, so readiness there is crawlability and page quality (references/10-capability-matrix.md).

Setup

• No mandatory secrets. Public-URL audits use curl + jq.
• Optional, raises quotas / unlocks platform reads:
  • PSI_API_KEY — PageSpeed Insights (CrUX + Lighthouse scores). Without it the anonymous quota runs out fast and state crux returns E_PSI with status 429.
  • lighthouse CLI — npm i -g lighthouse for full audit JSON.
  • GOOGLE_GSC_AUTH, GA4_AUTH — Search Console / GA4 refresh-token JSON.
  • Per-platform Marketing API env (see prereqs for the exact names): GOOGLE_ADS_*, META_ACCESS_TOKEN + META_AD_ACCOUNT_ID, MICROSOFT_ADS_*, LINKEDIN_ADS_*, TIKTOK_ADS_*, X_ADS_*, PINTEREST_ADS_*, REDDIT_ADS_*, SNAPCHAT_ADS_*, APPLE_SEARCH_ADS_*.
• Refuses any global / legacy API_KEY env — see Guardrails.
• Runtime state (findings, the API call log, snapshots, the refresh-docs cache) is written to ${XDG_STATE_HOME:-$HOME/.local/state}/snitch-adsready, never into the skill folder.

Tools

Read-only, JSON on stdout, errors as JSON on stderr:

Badges on stdout, not JSON — never pipe these into jq:

Setup help:

Utility: export <url>, verify <url>, refresh-docs, help. export and verify both require a URL and fail with E_USAGE without one.

Evidence rule

Three outcomes per check — Finding, Pass, or Skip — and each one carries its proof.

1. Every row cites where the verdict came from. In crawl mode that is the URL plus the exact JSON field and its value (.pixels.meta.detected = false). In source mode it is file:line plus the matched snippet. Quote the field, not a paraphrase of it.
2. A Pass carries evidence too — what was read and what came back clean. A bare "OK" is not a Pass.
3. A Skip carries the reason and what would unblock it — {locked:"meta-api"} means "set META_ACCESS_TOKEN", not "N/A".

Interpret the evidence before grading. Missing initial-HTML pixel/CMP signatures do not prove absent runtime wiring. Inspect the relevant consent states, tag-manager configuration, network events, navigation, and deduplication before reporting a behavioral defect. An installed tag does not prove conversions reach the intended account. Cite supplied traces as supplied, not as tests you ran. Select required platforms from the user's plan; unused platforms and publisher-only ads.txt on an advertiser site are Skip, not missing features.

score is a heuristic composite, not a Finding: report the components and weights so the reader can check the arithmetic, and never let a letter grade stand in for evidence. references/30-recipes.md carries the full report format.

How to use

1. Classify intent (audit, set up tracking, verify a fix, recommend a tool, plan a migration).

2. Call the smallest set of tools. Prefer state site <url> digest first — it covers all 10 platforms in one fetch. Add state crux and score only when CWV or a composite is needed.

3. Lazy-load the reference for each finding — see the area map below.

4. Synthesize the report per references/30-recipes.md. Group by area; sort 🔴 FAIL → 🟡 WARN → ⚪ SKIP → 🟢 PASS.

5. For every FAIL, offer to set it up. The mandated prompt is: "Want help setting this up? I can run setup <area> [platform] for a stepped plan."

6. When the user accepts, call setup <area> [platform] for the JSON plan, present each step in order, get confirmation per step, chain fix calls for auto steps, link to dashboards for manual ones.

7. For project file changes (fix pixel-install, fix consent-mode, fix capi-stub, fix ads-txt, fix robots, fix structured-data, fix security-headers, fix mobile-meta, fix verification-meta), the tool emits proposed contents + a diff:

   === FILE: <relative-path> ===
   === DIFF ===
   <unified diff>
   === CONTENT ===
   <full proposed file body>
   === END ===
   

   Apply with Edit / Write after the user confirms. The skill never writes inside the user's project. For platform-side secrets (CAPI tokens, MP secrets), the tool emits the dashboard URL and the env-var name — never type secret values yourself.

Area → reference map

Read the file whose area produced a finding. Nothing else.

Guardrails

• Refuses generic / global API key shapes (API_KEY= without a platform prefix, *_GLOBAL_KEY); redirects to scoped OAuth refresh tokens or service-account credentials per platform.
• No pixel before consent. fix pixel-install refuses to propose a tracking pixel into a project with no consent banner / CMP signal — it FAILs and points at fix consent-mode and recommend cmp instead. fix all runs consent before pixels for the same reason.
• Never lowers posture in a fix. No removing an existing CSP, no overwriting an existing ads.txt with fewer lines. A fix adds or it stops.
• Never mutates ad campaigns. No pausing, no bid changes, no creative. The skill reads, and sets up tracking. Campaign management belongs in the platform UI.
• Never verifies billing. It audits readiness, not whether a charge succeeded.
• Search surfaces are not judged here. Schema beyond the Product/Offer a shopping feed reads, llms.txt and AI-search content, hreflang and localized landing pages, AI-crawler policy for the non-ad assistants, and free business-listing profiles all belong to the marketing audit — when a finding lands there, call the Skill tool with "snitch-marketing" instead of grading it.
• fix is idempotent — a re-run no-ops when the target state is already met.
• Site-side parsers don't store fetched HTML on disk; the html slice prints the body but does not cache it.
• Respects robots.txt on the audited site; identifies as ads-ready-skill/1.
• A framework name cannot prove tracking or CWV failure. fit-matrix is integration context, not a migration gate. Recommend stack changes only against measured problems and the user's constraints; never install extra pixels, schema blocks, or sellers merely to raise a score.
• Missing performance evidence is unknown, not zero performance. Keep lab, URL field, and origin field data distinct; do not describe a lab score as field CWV conformance.
• Apple Search Ads / SKAdNetwork is iOS-only; with no iOS app, mark apple ⚪ SKIP with the reason — don't manufacture work.
• For an actual ad-account compromise, use the platform's native security tooling. Tracking incidents (conversions stopped, pixel stopped firing) are in scope — see references/13-incident-response.md.