find-service-providers
Use whenever the user wants to find, shortlist, vet, enrich, or research US professional-services firms — law, marketing, consulting, accounting, IT services, architecture, engineering, HR, PR, design, and similar B2B service providers. Triggers on requests like "find me a PPC agency in California", "shortlist three boutique IP law firms", "build a longlist of 50 mid-size IT consultancies", or "here are 12 agency domains — pull contact info and confirm which are US-based", even when the need is described indirectly without naming a category. Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog with filters for industry, services, location, size, ratings, and third-party listings. Skip when the user is asking for personal/consumer services for themselves (an individual's own legal, tax, or medical needs), non-US firms, individual freelancers, retail/ecommerce/SaaS-product companies, recruiting-an-employee tasks, or general web research that doesn't need a structured firm directory.
git clone --depth 1 https://github.com/nostrband/ServiceGraph /tmp/find-service-providers && cp -r /tmp/find-service-providers/skills/find-service-providers ~/.claude/skills/find-service-providersSKILL.md
# find-service-providers
Drive the **ServiceGraph API** (`https://api.servicegraph.co`) to find,
shortlist, and enrich US professional-services firms.
The API hosts several **datasets** behind a uniform per-dataset URL
shape (`/v1/datasets/:id/…`). This skill is for the agencies dataset —
**dataset id `pro_services`** — which holds 100k+ B2B service firms
classified across 22 industries with multi-tag service taxonomies,
location, size, and third-party rating signals.
Any HTTP client works (curl, fetch, requests). Examples below use curl.
## MCP server (preferred for authed calls)
If your agent harness has the **ServiceGraph MCP server** loaded
(`https://mcp.servicegraph.co`) — recognizable by tool names
containing `servicegraph` — prefer those tools over raw HTTP. The
MCP server uses OAuth 2.1 + PKCE so the harness handles credentials
in its own sandbox and no token value ever enters the LLM context.
Otherwise, fall through to the REST flow described below.
## API surface
Every endpoint requires the bearer (`Authorization: Bearer vk_…`).
There is no anonymous tier.
| Endpoint | Cost | Use it for |
|---|---|---|
| `GET /v1/datasets` | free | Discover available datasets. |
| `GET /v1/datasets/pro_services` | free | Full schema for this dataset (brief vs detail fields, allowed filters, unlock price, TTL). |
| `GET /v1/datasets/pro_services/fields[?include_values=1&q=]` | free | Filter-field catalog + DSL grammar. Call this first per session. |
| `GET /v1/datasets/pro_services/values/:field[?q=&limit=&offset=]` | free | Enumerate values for one field (e.g. legal `industry` / `state` / `service_provided` values). |
| `GET /v1/datasets/pro_services/check?filter=…` | free | Validate a filter string. Returns `{valid, normalized}` or `{valid:false, error}`. |
| `POST /v1/datasets/pro_services/translate-intent` | free | Body `{intent, model?}`. LLM-translates plain English → DSL filter + sanity-check row count. |
| `GET /v1/datasets/pro_services/search?filter=…&limit=&offset=` | free | Brief firm cards + per-row `unlock` hint. No url, no phone, no email. |
| `GET /v1/datasets/pro_services/:apex` | free | One row: always brief; **detail block only if caller has an active unlock** for `(user, dataset, apex)`. Idempotent, never charges. |
| `POST /v1/datasets/pro_services/unlocks` | **10 credits / firm** | Body `{apexes: [...]}`, max 100. Atomic batch — either all uncached apexes unlock, or none do (402 if balance short). Already-unlocked rows return `was_cached:true` with no extra charge. Detail TTL: 30 days. Returns brief + detail + per-item billing. |
| `GET /v1/me/credits` | free | Current credit balance. |
| `GET /v1/me/credits/transactions[?limit=&offset=]` | free | Spend history; unlock rows carry `(dataset_id, apex, expires_at)`. |
**Cost model in one paragraph.** Discovery, validation, search, and
brief reads are free. Detail data (apex, full url, phone, email,
social, address, legal name, platforms map) costs **10 credits per
firm** and lasts **30 days**. Re-fetching an unlocked firm within the
TTL is free — both the detail GET and the unlock POST honor the
cache. Charges are atomic per `POST /unlocks` call: a 402 leaves
balance untouched.
## Auth
Tokens are `vk_*` API keys minted in the dashboard. The user creates
them themselves; this skill never sees raw email/password.
**Security model — keep the token out of the LLM context.**
- **Never** read `.env`, `.env.local`, or any other credential file
into your context. The token's literal value must never appear in
the conversation.
- Every authed call goes through a shell wrapper so the token flows
from the user's environment / dotenv file into the
`Authorization` header without round-tripping through the LLM.
**First-call resolution:**
1. **Just try the call.** Dispatch via shell, sourcing `.env.local`
if present:
```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):
> "I need a ServiceGraph API key. Open
> **https://servicegraph.co/profile/api-keys**, sign in,
> click **Create key**, and copy the `vk_…` value.
>
> Then either export it in your shell —
> `export SERVICEGRAPH_API_KEY=vk_…` — or add the line
> `SERVICEGRAPH_API_KEY=vk_…` to `.env.local` in this directory.
> Tell me when done and I'll retry. Please don't paste the key
> into chat — keep it out of the LLM context."
3. **After the user signals ready**, re-dispatch the same call. If a
later call returns `401`, the key was revoked or rotated — re-prompt.
For the user's convenience: if `SERVICEGRAPH_API_KEY` is already set
or already in `.env.local`, the very first call will succeed and the
prompt step never happens.
## Filter DSL
One query parameter, 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` matches
any of the three.
3. **Negation is `-x` or `NOT x`.** Negative literals inside a comma
list are **not** allowed: `state:CA,-NY` is rejected. Use
`state:CA -state:NY`.
4. **Bareword = keyword search.** Any IDENT or NUMBER not followed by
an operator becomes a free-text substring across name / brand /
title / meta / legal_name. MultiUse whenever the user wants to find, shortlist, vet, or enrich US AI/ML/data consulting firms (consultancies) — AI/ML development, MLOps, generative AI / LLM apps (RAG, chatbots, agents), computer vision, NLP, recommendation systems, data engineering, BI/analytics. Triggers on "find an AI/ML consulting firm to build our recommendation engine", "shortlist three RAG/LLM consultancies for an enterprise chatbot", "compare three AI/ML consulting firms with strong ratings", or "pull contact info for these 8 AI consultancy domains", even when described indirectly (we want to use AI for X, deploy ML to production). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Defer to find-software-developer for general app/backend work where AI is just a feature. Skip in-house ML/data hires, LLM/AI-tool comparisons (ChatGPT vs Claude), "how do I fine-tune X" DIY questions, AI courses for individuals, non-US firms, individual freelancers.
Use whenever the user wants to find, rank, or shortlist directories and listing sites where they can submit an AI product — an AI tool, AI app, AI agent, or agent skill / plugin — to get backlinks, referral traffic, and discovery. Triggers on "where can I list my AI tool", "directories to submit my AI agent", "agent-skills directories", "best AI tool directories for backlinks", "where do I get my GPT/Claude app discovered", or "pull submission details for these AI-directory domains", even when described indirectly (we built an AI agent, where do we get it in front of people). Drives the ServiceGraph API (api.servicegraph.co) — a catalog of 1,000+ product directories enriched with Domain Rating, backlinks, and organic traffic. Defer to find-mcp-directories for MCP-server listings specifically, and to find-product-directories for general SaaS/software/app launches with no AI angle. Skip finding an AI consultancy/agency to hire (use find-ai-consultancy), comparing AI products ("ChatGPT vs Claude"), building an AI tool (do-the-work), and AI link-building *services*.
Use whenever the user wants to find, shortlist, vet, or enrich US accounting and tax firms (CPA firms) — financial-statement audit, SOC 1/2 audit, corporate tax, bookkeeping for businesses, advisory/fractional CFO, M&A diligence, 409A valuations, R&D tax credits, IPO readiness, sales-and-use tax. Triggers on "find me a CPA firm for our delaware c-corp series A audit", "shortlist three audit firms with SaaS experience", "we need a tax advisor for our M&A", or "pull contact info for these 10 accounting firm domains", even when described indirectly (audit our books, fractional CFO support, file our 1120). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip personal/consumer tax preparation (1040, individual estate, retirement planning), in-house controller/CFO hires, "how do I file my taxes" DIY questions, accounting-software comparisons (QuickBooks vs Xero), non-US firms, individual freelance bookkeepers.
Use whenever the user wants to find, shortlist, vet, or enrich US cybersecurity firms — pen-testing/red team, security audits, vCISO, SOC 2 readiness, incident response, managed SOC, IAM, cloud security, and AppSec. Triggers on "find me a pen-testing firm for our SOC 2 audit", "shortlist three vCISO services for our healthcare-tech startup", "we need an incident response retainer", or "pull contact info for these 8 security firm domains", even when described indirectly (we got breached, prepare us for the compliance audit, get us SOC 2 ready). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip in-house security hires, "how do I patch CVE-X" or "configure firewall Y" DIY questions, security-product reviews (CrowdStrike vs SentinelOne, etc.), generic security knowledge questions, consumer/personal security advice, non-US firms, individual freelancers and bug-bounty hunters.
Use whenever the user wants to find, shortlist, vet, or enrich US design and creative agencies — graphic design, UX/UI, product design, brand identity, packaging, illustration, motion design, and creative direction. Triggers on "find me a UX/UI design agency for our SaaS product", "shortlist three brand-identity studios in NY", "packaging design firm for a CPG launch", or "pull contact info for these 10 design studio domains", even when described indirectly (brand refresh, design our app, build our visual system). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Defer to find-marketing-agency for marketing-led engagements where design is one of several services. Defer to find-web-developer when the deliverable is a built website. Skip in-house designer hires, "design me a logo" DIY asks, design-software comparisons, consumer/personal-design (weddings, hobby projects), non-US firms, individual freelancers.
Use whenever the user wants to find, shortlist, vet, or enrich US engineering firms — civil, structural, MEP, mechanical, electrical, geotechnical, transportation, environmental, and manufacturing. **For real-world engineering (buildings, infrastructure, manufacturing) — NOT software engineering.** Triggers on "find civil engineering firms in Florida for transportation", "shortlist three structural engineering firms with high-rise experience", "MEP consultancy for a hospital project", or "pull contact info for these 12 engineering firm domains", even when described indirectly (PE-stamped drawings, building-permit review). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Defer software-dev / "engineering team" / SaaS-architecture asks to find-software-developer. Skip in-house engineering-manager hires, DIY questions, software-product comparisons (Revit, AutoCAD), non-US firms, individual freelancers.
Use whenever the user wants to find, shortlist, vet, or enrich US B2B law firms — corporate, IP/patent, M&A and securities, employment, commercial litigation, regulatory/compliance, data privacy/cyber, real estate, and tax. Triggers on "find three boutique IP law firms in California", "shortlist M&A counsel for a Series-B fundraise", "patent prosecution for our hardware startup", or "pull contact info for these 10 law firm domains", even when described indirectly (outside counsel, cap-table review, GDPR/SOC2 oversight). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip personal/consumer legal services where the user is the end client (divorce, personal injury, criminal defense, family law, estate planning, wills) — the catalog is B2B-only. Also skip in-house GC hires, "is this NDA enforceable" DIY questions, non-US firms, individual freelancers.
Use whenever the user wants to find, shortlist, vet, or enrich US management consultancies — strategy, operations, executive coaching, leadership development, org-development/change management, PMO/program management, sales/revenue operations consulting. Triggers on "find me three top strategy consultancies in California", "shortlist boutique ops-consulting firms with healthcare experience", "we need an executive coach for our new CEO", or "pull contact info for these 10 consulting firm domains", even when described indirectly (post-merger integration help, change-management partner, fractional COO). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip in-house strategy hires, "help me build a strategy" do-the-work asks, framework comparisons (Lean vs Agile, BCG matrix, etc.), academic/MBA-program questions, life/career coaching for individuals, non-US firms, individual freelancers.