Find Marketing Agency

SKILL.md

---
name: find-marketing-agency
description: Use whenever the user wants to find, shortlist, vet, or enrich US marketing agencies — including branding, content marketing, PPC/paid media, social media, email marketing, performance/demand-gen, video production, and full-service digital agencies. Triggers on requests like "shortlist three B2B branding agencies in California", "find a PPC shop with ecommerce experience", "we need a content marketing partner for a SaaS launch", or "pull contact info for these 12 agency domains", even when the need is described indirectly. Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings, and third-party listings. Skip SEO-only asks (use find-seo-agency), web/software-development asks (use find-web-developer or find-software-developer), recruiting an in-house marketing hire, "write me a marketing plan" do-the-work asks, non-US firms, individual freelancers, marketing-software-product recommendations, and consumer/personal-brand asks.
version: "0.4.0"
metadata:
  api_base: https://api.servicegraph.co
  dataset_id: pro_services
  industry: marketing_agency
---

# find-marketing-agency

Drive the **ServiceGraph API** (`https://api.servicegraph.co`) to find,
shortlist, and enrich US marketing agencies via the `pro_services`
dataset. The catalog has tens of thousands of US marketing firms
tagged across ~26 service sub-tags including `branding`,
`content-marketing`, `ppc`, `social-media-marketing`, `email-marketing`,
`web-design`, `video-production`, `inbound-marketing`,
`marketing-strategy`, `conversion-optimization`, and
`ecommerce-marketing`. (Note: there is no `performance-marketing` or
`demand-gen` / `demand-generation` tag — those user-phrasings map to
`inbound-marketing` / `marketing-strategy` / `conversion-optimization`
plus a keyword fallback.)

**Always pin `industry:marketing_agency`.** This skill exists to do
that automatically — the user shouldn't have to think about catalog
taxonomy.

Any HTTP client works (curl, fetch, requests). Examples below use curl.

## Sibling skills — defer when scope is narrow

If the user's ask is **strictly** one of the following, defer to the
dedicated skill:

- Strictly SEO/search-ranking work → `find-seo-agency`
- Strictly web/app/software development → `find-web-developer` /
  `find-software-developer`

If the user wants a marketing agency that *also* does SEO or web work
as part of a broader engagement, this skill is correct — pin
`industry:marketing_agency` and add the relevant `service_provided:`
tags.

## MCP server (preferred for authed calls)

If your harness has the ServiceGraph MCP server loaded (recognizable
by tool names containing `servicegraph`), prefer those tools — the
harness handles credentials in its own sandbox via OAuth 2.1 + PKCE,
so no token enters LLM context. Otherwise use the REST flow below.

## API surface (dataset id: `pro_services`)

Every endpoint requires the bearer (`Authorization: Bearer vk_…`).
There is no anonymous tier.

| Endpoint | Cost | Use it for |
|---|---|---|
| `GET /v1/datasets/pro_services/fields[?include_values=1&q=]` | free | Filter-field catalog + DSL grammar. Call first per session. |
| `GET /v1/datasets/pro_services/values/:field[?q=&limit=]` | free | Enumerate values for one field. |
| `GET /v1/datasets/pro_services/check?filter=…` | free | Validate a filter. Returns `{valid, normalized}` or `{valid:false, error}`. |
| `POST /v1/datasets/pro_services/translate-intent` | free | `{intent}` → LLM-generated DSL filter + sanity count. |
| `GET /v1/datasets/pro_services/search?filter=…&limit=&offset=` | free | Brief firm cards + per-row `unlock` hint + `total`. |
| `GET /v1/datasets/pro_services/:apex` | free | Single row brief; **detail block only if unlocked**. |
| `POST /v1/datasets/pro_services/unlocks` | **10 credits / firm** | `{apexes:[...]}` ≤100. Atomic batch; 30-day TTL on detail; `was_cached:true` rows free. |
| `GET /v1/me/credits` | free | Balance. |

**Cost model.** Discovery / validation / search / brief reads are
free. Detail (url, phone, email, social, address, full `platforms`
map) costs **10 credits per firm** and lasts **30 days**. Re-fetching
an unlocked firm within TTL is free.

## Auth

Tokens are `vk_*` API keys minted in the dashboard.

**Keep the token out of the LLM context** — never read `.env*` into
your context; dispatch every authed call through a shell wrapper.

1. **Just try the call** through a shell wrapper that sources
   `.env.local`:

   ```bash
   ( set -a; [ -f .env.local ] && . ./.env.local; set +a;
     curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \
          'https://api.servicegraph.co/v1/datasets/pro_services/fields' )
   ```

2. **On `401 unauthorized`**, prompt the user (don't accept the key in chat):

   > "Open **https://servicegraph.co/profile/api-keys**, sign in,
   > click **Create key**, and copy the `vk_…` value. Then add
   > `SERVICEGRAPH_API_KEY=vk_…` to `.env.local` here (or export it
   > in your shell). Tell me when done. Please don't paste the key
   > into chat."

3. **Retry** the same call after the user signals ready. A later 401
   means the key was rotated/revoked — re-prompt.

## Filter DSL

GitHub-search-style.

```
filter   := orExpr
orExpr   := andExpr ("OR" andExpr)*
andExpr  := notExpr (("AND")? notExpr)*    # whitespace = implicit AND
notExpr  := ("NOT" | "-") notExpr | atom
atom     := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op       := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value    := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER          # → keyword:<bareword>
```

**Four rules that bite:**

1. **AND binds tighter than OR.** `a OR b c` parses as `a OR (b AND c)`. Use parens.
2. **Comma list = OR within one predicate.** `state:CA,NY,TX` = any of three.
3. **Negation is `-x` or `NOT x`.** `state:CA,-NY` is rejected; use `state:CA -state:NY`.
4. **Bareword = keyword search.** Free-text substring across name / brand / title / meta / legal_name. Multiple barewords AND. Wrap multi-word phrases in double quotes (`keyword:"foo bar"`).

**Marketing-flavored examples** (validate yours with `/check`):

```
industry:marketing_agency service_provided:branding@high
industry:marketing_agency service_provided:ppc service_provided:content-marketing
industry:marketing_agency state:CA,NY -company_size_signal:solo
industry:marketing_agency (service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high)
b2b industry:marketing_agency service_provided:content-marketing@high
industry:marketing_agency rating>=4 review_count_total>=20 has:clutch
industry:marketing_agency NOT (service_provided:seo OR service_provided:web-development)
```

## Identifying firms — `apex`

Firms are identified by their **apex domain** (`ogilvy.com`, not
`www.ogilvy.com/about`). Strip user-supplied URLs to the apex before
calling `:apex` endpoints or building unlock batches.

## Recipes

### A. Branding agency in a state

User: *"Three B2B branding agencies in California for a Series-A SaaS company."*

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+state:CA+service_provided:branding@high+b2b&limit=10
# → 10 brief cards + total + per-row unlock.status

# Present, get user's pick of 3. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
# → brief + detail for all 3
```

### B. PPC + ecommerce vertical

User: *"PPC shop that specializes in ecommerce."*

The catalog has a real `ecommerce-marketing` tag — pin it alongside
PPC for tighter shortlists than relying on the `ecommerce` keyword
alone:

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ppc+service_provided:ecommerce-marketing&limit=10
```

### C. Multi-tag intersection — content + email + B2B vertical

User: *"Content marketing partner for a SaaS launch — should also do email."*

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:content-marketing@high+service_provided:email-marketing+saas
```

If the NY-area pool collapses with a `fintech`/`saas` keyword (it
tends to — vertical pins under-perform on agency copy), drop the
keyword and surface vertical experience to the user from briefs.

### D. Performance / demand-gen (indirect intent)

User: *"Someone to run our quarterly demand-gen campaigns and own the funnel."*

The catalog has **no** `performance-marketing` / `demand-gen` /
`demand-generation` tag — map to `inbound-marketing`,
`marketing-strategy`, or `conversion-optimization`, plus a keyword
for the user's wording:

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+(service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high OR service_provided:conversion-optimization@high)+(demand OR funnel)&limit=10
```

If breakdowns are thin, drop `@high` or fall back to pure keyword.

Alternatively, use the intent translator:

```
POST /v1/datasets/pro_services/translate-intent
  { "intent": "agency to run quarterly demand-gen campaigns and own the funnel" }
```

### E. Quality threshold (third-party signals)

User: *"Compare three social media agencies that have worked with Fortune 500 — high evidence."*

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:social-media-marketing@high+rating>=4+review_count_total>=20+has:clutch&limit=10
```

`fortune 500` is hard to filter structurally; let the user pick from
briefs or add `fortune` as a keyword.

### F. DTC ecommerce agencies

User: *"Paid-social agency for our DTC apparel brand."*

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ecommerce-marketing+service_provided:social-media-marketing+dtc&limit=10
```

### G. Video production

User: *"Video production studio for a 90-second product launch film, NYC or LA."*

```
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:video-production+state:NY,CA&limit=10
```

State is HQ-only; surface city from the unlocked detail for NYC-vs-LA disambiguation.

### H. BYO apex list — enrich domains

User pastes 8–20 domains:

1. `GET /v1/datasets/pro_services/:apex` per domain — free brief
   (404 = not in catalog, no charge). Flag misses.
2. User picks N to fully enrich. `POST /unlocks` with all of them =
   **10×N credits**, single atomic charge, detail bundles returned.
3. Within 30-day TTL, repeated unlock POSTs are free.

## Gotchas

- **Always pin `industry:marketing_agency`.** Without it, `service_provided:branding` matches design firms, IT services, and others.
- **Defer to sibling skills for narrow asks.** SEO-only → `find-seo-agency`. Strictly web/app development → `find-web-developer` / `find-software-developer`.
- **Briefs DO include `apex`, `name`, `industry`, `service_provided`, state, ratings.** They DON'T include `url`, `phone_primary`, `email_primary`, `legal_name`, `address_full`, full `platforms`. Those require an unlock.
- **`not_found` / `not_in_dataset` 404 is not a bug.** Apex isn't in `pro_services` (might be in another dataset). Skip; not charged.
- **Catalog is US-only B2B.** Refuse non-US asks, individual freelancers, and personal-brand consulting for the user themselves.
- **Multi-word phrases must be split or quoted.** `b2b saas` parses as two AND'd keywords; `"b2b saas"` is one phrase.
- **Unlock is atomic.** `POST /unlocks` with 5 apexes either charges (up to) 50 credits or leaves balance untouched on 402. Plan the batch.
- **Within-TTL re-views are free.** Re-running unlock on an apex still inside its 30-day window returns `was_cached:true`.

## Errors

JSON envelope: `{"error": {"code": "...", "message": "..."}}`.

| Status | Code | What to do |
|---|---|---|
| 400 | `filter_parse_error` | `position` included; fix and re-validate with `/check`. |
| 400 | `kind_in_filter` | Strip any `kind:` from filter — URL is authoritative. |
| 400 | `field_not_in_dataset` | Field isn't allowed on `pro_services`; drop it. |
| 400 | `invalid_apex` | Re-normalize to apex. |
| 401 | `unauthorized` / `invalid_audience` | Re-prompt for a fresh `vk_…`. |
| 402 | `insufficient_credits` | `needed` and `balance` in payload; nothing charged. |
| 404 | `not_found` / `not_in_dataset` | Skip; not charged. |
| 429 | `rate_limited` | Honor `Retry-After`. |

## End-to-end example

User: *"Shortlist three B2B branding agencies in California for a
Series-A SaaS company — high evidence on branding, ideally with at
least a 4-star rating."*

```
# 1. Discover (once per session)
GET /v1/datasets/pro_services/fields?include_values=1
# Confirms 'branding' is in service_provided, rating is numeric.

# 2. Validate + scope (free)
GET /v1/datasets/pro_services/check?filter=industry:marketing_agency+state:CA+service_provided:branding@high+rating>=4+b2b

# 3. Search briefs (free)
GET /v1/datasets/pro_services/search?filter=...&limit=10
# → 10 cards + total + per-row unlock.status

# 4. Present, get pick of 3. "Unlocking 3 firms = 30 credits, 30-day TTL."

# 5. Atomic unlock (charges 30 credits)
POST /v1/datasets/pro_services/unlocks
  { "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }

# 6. (Optional) Confirm balance
GET /v1/me/credits
```