Use whenever the user wants to find, shortlist, vet, or enrich US recruiting and staffing firms — executive search/retained search, RPO, tech/sales/healthcare recruiting, contingent/contract staffing, and temp staffing. Triggers on "find me an executive search firm for a CFO search", "shortlist three retained-search boutiques in NY focused on tech", "we need RPO support for a 50-engineer hiring push", or "pull contact info for these 8 staffing firm domains", even when described indirectly (need help hiring at scale, executive recruiter for senior roles). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip when the user wants to hire someone as their own employee (job-board questions, in-house recruiter hires, "where should I post the role"), individual job-seekers looking for recruiters to represent them, candidate-side career coaching, non-US firms, individual freelance recruiters.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use whenever the user wants to find, shortlist, vet, or enrich US recruiting and staffing firms — executive search/retained search, RPO, tech/sales/healthcare recruiting, contingent/contract staffing, and temp staffing. Triggers on "find me an executive search firm for a CFO search", "shortlist three retained-search boutiques in NY focused on tech", "we need RPO support for a 50-engineer hiring push", or "pull contact info for these 8 staffing firm domains", even when described indirectly (need help hiring at scale, executive recruiter for senior roles). Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings. Skip when the user wants to hire someone as their own employee (job-board questions, in-house recruiter hires, "where should I post the role"), individual job-seekers looking for recruiters to represent them, candidate-side career coaching, non-US firms, individual freelance recruiters.
Drive the ServiceGraph API (https://api.servicegraph.co) to find,
shortlist, and enrich US recruiting and staffing firms via the
pro_services dataset.
This skill is for procuring an external recruiting/staffing firm
to do hiring on the user's behalf. It is NOT for:
recruiting an in-house employee (the user wants to hire someone for their own team — that's job-posting, not procurement),
candidate-side asks (an individual job-seeker looking for someone to represent them).
Both share keyword overlap with the positive case ("recruiter", "hire"), so the boundary matters.
Always pin industry:hr_recruiting_staffing. Sub-types
(executive search, RPO, contingent staffing, temp, vertical
specializations) are NOT separate tags — sub-type specialization is
a keyword substring search on firm text.
Any HTTP client works (curl, fetch, requests). Examples below use curl.
When NOT to use this skill
"I want to hire a [role] for my team — where should I post the job?" → recruiting-an-employee.
"Find me a recruiter to represent me in my job search" → candidate side.
"Hire an in-house recruiter / Head of Talent" → recruiting an employee.
"Help me write a job description" → DIY/do-the-work.
ATS or HR-software comparisons (Greenhouse vs Lever, Workday).
Career coaching for individual job-seekers.
Non-US firms / individual freelance recruiters.
Prerequisites
ServiceGraph access, either:
the ServiceGraph MCP server (https://mcp.servicegraph.co) loaded in
your harness — this plugin's .mcp.json wires it up; OAuth 2.1 + PKCE
keeps credentials in the harness sandbox — or
a ServiceGraph API key (vk_…, minted at
https://servicegraph.co/profile/api-keys) available as
SERVICEGRAPH_API_KEY in the environment or .env.local for the REST
path (setup steps under Auth below).
An HTTP client for the REST path — the examples use curl.
Instructions
The loop is free-first: discovery, validation, search, and brief reads cost
nothing; only unlock after the user confirms the spend.
Pick the call path — the ServiceGraph MCP tools if loaded, otherwise the
REST flow (MCP server and Auth sections below).
GET /v1/datasets/pro_services/fields?include_values=1 — confirm the
fields and values you plan to filter on exist.
Build the filter (Filter DSL below) and validate it with
GET /v1/datasets/pro_services/check — or draft it from plain English via
POST /v1/datasets/pro_services/translate-intent.
GET /v1/datasets/pro_services/search — present the free brief cards and
let the user pick.
Quote the unlock cost (10 credits per row, 30-day TTL) and get an explicit
go-ahead.
POST /v1/datasets/pro_services/unlocks with the chosen apexes; report the
revealed detail.
GET /v1/me/credits to report the remaining balance when asked.
MCP server (preferred for authed calls)
If your harness has the ServiceGraph MCP server loaded (tools
containing servicegraph), prefer those — OAuth 2.1 + PKCE keeps the
token in the harness sandbox. Otherwise use the REST flow below.
API surface (dataset id: pro_services)
Every endpoint requires the bearer (Authorization: Bearer vk_…).
No anonymous tier.
Endpoint
Cost
Use it for
GET /v1/datasets/pro_services/fields[?include_values=1]
free
Confirm hr_recruiting_staffing is in the industry value list.
GET /v1/datasets/pro_services/check?filter=…
free
Validate filter.
POST /v1/datasets/pro_services/translate-intent
free
{intent} → DSL filter + sanity count.
GET /v1/datasets/pro_services/search?filter=…&limit=
free
Brief firm cards + per-row unlock hint + total.
GET /v1/datasets/pro_services/:apex
free
One row brief; detail only if unlocked.
POST /v1/datasets/pro_services/unlocks
10 credits / firm
{apexes:[...]} ≤100; atomic; 30-day TTL on detail.
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.
Auth
vk_* API keys minted in the dashboard. Keep the token out of the
LLM context — never read .env* into your context; dispatch via
shell.
Try the call first through a shell wrapper that sources .env.local:
"Open https://servicegraph.co/profile/api-keys, create a
key, and add SERVICEGRAPH_API_KEY=vk_… to .env.local here
(or export it). Tell me when done. Please don't paste the key
into chat."
Retry after the user signals ready.
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: AND binds tighter than OR (use parens);
comma list = OR within one predicate; negation is -x or NOT x;
bareword = keyword search (quote multi-word phrases).
Recruiting-flavored examples (validate yours with /check):
Firms are identified by their apex domain (korn-ferry.com, not
www.korn-ferry.com/about).
Output
All responses are JSON.
Search returns free brief firm cards — apex, name, location, and
rating signals — plus a per-row unlock hint and the match total. Briefs
never include url, phone_primary, email_primary, legal_name,
address_full, or the full platforms map.
Unlock (POST …/unlocks) returns each unlocked firm's detail block —
contact fields, address, socials, the platforms map — plus per-item
billing; detail stays readable for 30 days.
Errors arrive as a JSON envelope
{"error": {"code": "…", "message": "…"}} — see Errors below.
Examples
A. Executive search for a CFO
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+executive+search&limit=10
# Present, get 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"] }
B. Retained boutique in a state, vertical
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+retained+state:NY+tech+-company_size_signal:large_50plus&limit=10
C. RPO for a hiring surge
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+rpo+(tech OR engineering)&limit=10
D. Indirect intent — "scaling fast, need help hiring"
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+(rpo OR contingent)&limit=10
Or use the translator:
POST /v1/datasets/pro_services/translate-intent
{ "intent": "RPO or volume recruiting partner for a 50-engineer hiring push" }
E. Vertical: healthcare staffing
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+healthcare+state:OH,IL,MI,IN,WI,MN&limit=10
F. Quality threshold + tech-sector
GET /v1/datasets/pro_services/search?filter=industry:hr_recruiting_staffing+executive+search+tech+rating>=4&limit=10
G. BYO apex list — enrich domains
User pastes 8–20 staffing/recruiting firm domains:
GET /v1/datasets/pro_services/:apex per domain — free brief
(404 = not in catalog, no charge).
User picks N to fully enrich. POST /unlocks = 10×N credits,
atomic, detail returned.
Re-runs within 30-day TTL are free.
Gotchas
Always pin industry:hr_recruiting_staffing. Without it, "recruiter" / "executive search" keywords leak into other industries.
Distinguish "find me a recruiting firm" (procurement, fires) from "find me a recruiter / hire a recruiter for our team" (recruiting-an-employee, refuses). When ambiguous, lean on context: explicit firm/agency/RPO language or volume framing → procurement; "for our team" / "to post the job" / "I want to hire" → in-house hire.
Candidate-side asks ("represent me as a candidate", "find me a job") are out of scope.
Career coaching for individuals is a different need (and shares the executive-coaching keyword with management consulting). Refuse — this skill is firm-procurement.
Sub-types are keyword-only. Multi-word sub-types split into ANDed barewords unless quoted ("executive search" → one phrase).
Briefs DO include apex, name, location, 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 = not in pro_services. Skip; not charged.
Unlock is atomic. N apexes either all charge (up to 10×N credits) or none on 402.
