getaero-io/gtm-eng-skills / skills/deepline-ads-audiences
deepline-ads-audiences
VerifiedUse this skill when building, enriching, auditing, or uploading B2B paid ads audiences to Google Customer Match, Meta/Facebook Custom Audiences, or LinkedIn Matched Audiences. Triggers on phrases like '/deepline-ads-audience', '/deepline-ads-audiences', 'upload this audience', 'create custom audiences', 'personal email hashes', 'increase Facebook match rate', 'Google ads audience', 'Meta audience', 'FB audience', or any workflow that turns CRM/customer/contact data into paid ads upload lists. Skip for outbound prospecting sequences, cold email, or pure campaign copywriting.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.6 KB |
| plays/audit-no-double-hash.play.ts | script | 3.1 KB |
| plays/build-contactout-hash-pool.play.ts | script | 9.7 KB |
| plays/build-hash-only-audience.play.ts | script | 7.0 KB |
| plays/enrich-audience-waterfall.play.ts | script | 16.7 KB |
| plays/evaluate-leadmagic-personal-email.play.ts | script | 3.7 KB |
| plays/evaluate-personal-email-provider.play.ts | script | 13.8 KB |
| plays/report-google-coverage-lift.play.ts | script | 8.6 KB |
| plays/shared/audience-hash.ts | script | 10.8 KB |
| plays/upload-facebook-google-hash-only-audience.play.ts | script | 5.4 KB |
| plays/upload-google-hash-only-audience.play.ts | script | 3.3 KB |
| recipes/enrich-and-upload-facebook-google.md | markdown | 6.9 KB |
| recipes/max-coverage-audience.md | markdown | 11.3 KB |
| recipes/sample-abm-segment-example.md | markdown | 4.9 KB |
| shared/audience-basics.md | markdown | 4.5 KB |
| shared/contactout-hash-pool.md | markdown | 7.9 KB |
| shared/meta-connection.md | markdown | 3.7 KB |
| shared/upload-failure-modes.md | markdown | 9.3 KB |
| skill-metadata.json | config | 3.3 KB |
recipes/enrich-and-upload-facebook-google.md
View on GitHub# Enrich And Upload Paid Ads Audiences
Use this recipe when the user wants a B2B audience enriched with personal identifiers and uploaded to Meta/Facebook and Google. The output is paid ads audiences, not outbound contacts.
## When To Use
Use this recipe for:
- ABM audiences from CRM, Snowflake, Salesforce, HubSpot, or customer uploads.
- "Increase match rate on Facebook/Google" requests.
- "Use personal emails for ads, not outbound" requests.
- Enriched versus unenriched audience tests.
Skip this recipe for:
- Cold outbound sequences.
- One-off consumer targeting without source-list rights.
- Mobile-phone buying unless the user explicitly asks and approves cost.
## Inputs
Start with a project-local working directory because enrichment outputs are paid artifacts. Run this from the project root; the play commands below run from this skill's folder, so `./plays/...` resolves and `$WORKDIR` stays absolute:
```bash
WORKDIR="$PWD/deepline/data/<customer>-ads-audience" && mkdir -p "$WORKDIR" && echo "$WORKDIR"
```
The source CSV should preserve lineage fields:
| Field | Why |
| --------------------------- | ------------------------------------------------------------- |
| `source_row` or `person_id` | Reconcile rows after enrichment and upload. |
| `work_email` | Baseline Google and Meta hash input. |
| `linkedin_url` | Personal-email fallback providers usually need it. |
| `first_name`, `last_name` | Identity checks and fallback providers. |
| `company`, `domain` | ABM review and provider context. |
| `country_code` | Keep US-only default unless the user confirms broader rights. |
## Waterfall
Start with the cost-effective hash-provider pass:
1. Work-email baseline, normalized and SHA-256 hashed.
2. Aviato hash provider on all eligible rows with LinkedIn/profile context, including rows that already have work emails. Pass through 64-character personal email hashes as-is.
3. LimaData audience identifier hashes on rows still missing a personal hash after Aviato, or on all eligible rows first when that is more cost-effective.
Keep work-email rows in the enrichment pool until they receive a personal hash or the provider ladder is exhausted.
Stop there by default. Report coverage lift, unique hashes added, contacts still missing personal hashes, and Deepline spend.
Then ask the user whether they want to spend more per contact on broader raw personal-email providers. Quote the current rate from `deepline describe <tool_id>` rather than a figure written here: rates change, and a stale number in an approval gate makes users agree to a price that no longer holds. Only after explicit approval, run the expanded pass:
4. LeadMagic personal email on rows still missing personal hashes, then normalize and hash once.
5. ContactOut free personal-email pre-check, then paid reveal only for true rows.
6. Optional later fallbacks: Wiza, Datagma, Crustdata, Prospeo, FullEnrich, PDL.
Every provider layer should report:
- attempted rows
- row hits
- hashes seen
- unique hashes added
- failures
- estimated and actual cost
If the user asks for "max coverage", "highest match rate", "keep increasing coverage", or a target such as "get closer to 75% coverage", switch to `recipes/max-coverage-audience.md` before spending beyond Aviato/LimaData. The max-coverage recipe adds explicit stop conditions, LinkedIn repair, broader personal-email fallback, optional phone hashes, and platform-readback economics.
## Build Hash-Only Payload
Use the bundled play when the CSV already contains first-party emails plus provider hash or personal email columns. It returns two datasets, `baseline_rows` and `enriched_rows`; write each to its own CSV in the same run:
```bash
deepline run ./plays/build-hash-only-audience.play.ts --input '{"file":"'"$WORKDIR"'/source.csv"}' --csv-out baseline_rows="$WORKDIR/baseline_hash_only.csv" --csv-out enriched_rows="$WORKDIR/enriched_hash_only.csv"
```
If `deepline run --help` reports an unknown command, ask the user to update the Deepline CLI (https://code.deepline.com/INSTALL.md) before continuing.
## Audit Before Upload
Run the no-double-hash audit. This catches the most expensive silent failure: hashing a provider hash again and uploading a valid-looking but useless identifier. `providerHashFile` is the source CSV, which holds the provider hash columns:
```bash
deepline run ./plays/audit-no-double-hash.play.ts --input '{"payloadFile":"'"$WORKDIR"'/enriched_hash_only.csv","providerHashFile":"'"$WORKDIR"'/source.csv","providerHashColumns":["aviato_hash","limadata_hash","email_sha256","hashed_personal_email_sha256"]}'
```
Pass criteria:
- malformed hashes: 0
- duplicate hashes: 0 after dedupe
- raw email fields in upload payload: false
- provider hashes missing from payload: 0
- double-hashed provider hashes present: 0
A live upload without a no-double-hash audit is not acceptable for this workflow.
## Upload To Facebook And Google
Discover accounts first. Show account name and ID to the user before upload.
```bash
deepline search "connected ad platform login -> accessible ad accounts"
deepline search "hashed emails and phones -> custom audience upload"
```
Use the combined play when both channel IDs are ready:
```bash
deepline run ./plays/upload-facebook-google-hash-only-audience.play.ts --input '{"file":"'"$WORKDIR"'/enriched_hash_only.csv","audience_name":"<segment> enriched hash-only <date>","google_account_id":"<google_customer_id_without_dashes>","meta_ad_account_id":"act_<meta_ad_account_id>","meta_audience_id":"<existing_meta_custom_audience_id>"}'
```
Notes:
- Google play path creates a new Customer Match audience, uploads rows, and reads status back.
- Meta path syncs rows into an existing Custom Audience because the live tool surface may expose sync without create. If a create tool exists in the current catalog, create the Meta audience first, then pass its ID to the play.
- Use `append` for Google on a newly created list.
- Use `replace` for Meta so the custom audience mirrors the hash-only payload.
Use the same create/sync/readback pattern for Meta with the current `meta_audiences` tools. If Meta create is not exposed, ask for an existing Custom Audience ID and sync into that audience only after the user confirms the account name and ID.
## Report
Final report should include:
- Source list name and row count.
- Baseline hash count.
- Enriched hash count.
- Provider lift by layer.
- Audit pass/fail values.
- Google account name and ID, audience ID, uploaded count, invalid count, readback status.
- Meta ad account name and ID, audience ID, uploaded count, invalid count, readback status if available.
- Match-rate caveat: Meta may take about 1 hour to populate; Google may take 24 to 48 hours.
Do not claim a match rate until the platform returns it. Report `null` as processing, not as zero.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |