From servicegraph
Finds, shortlists, and enriches US engineering firms (civil, structural, MEP, etc.) via the ServiceGraph API. For real-world engineering, not software.
How this skill is triggered — by the user, by Claude, or both
Slash command
/servicegraph:find-engineering-firmThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Drive the **ServiceGraph API** (`https://api.servicegraph.co`) to find,
Drive the ServiceGraph API (https://api.servicegraph.co) to find,
shortlist, and enrich US real-world engineering firms — buildings,
infrastructure, energy, manufacturing — via the pro_services
dataset. The catalog tags firms with industry:engineering_services
and a ~23-tag service sub-taxonomy.
This is NOT for software engineering. "Software engineering firm", "engineering team", "engineering manager hire", "system architecture review" — those are all software-developer territory. The first thing this skill confirms is that the user means real engineering, not software.
Always pin industry:engineering_services. Note the _services
suffix — older docs sometimes show industry:engineering but the
literal pin returns zero results in the live catalog. Sub-disciplines
are typically structured service_provided tags
(civil-engineering, structural-engineering, mep-engineering,
etc.) — confirm exact names via
/v1/datasets/pro_services/fields?include_values=1. Surveying is
surveying-mapping, not surveying.
Any HTTP client works (curl, fetch, requests). Examples below use curl.
The dominant failure mode is firing on software-engineering asks. Refuse those.
find-software-developer.find-architecture-firm covers that industry (when it exists). This skill covers engineering disciplines that work with architects (structural, MEP, civil), but the architect-of-record procurement is a different fire.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.
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 engineering_services industry value and sub-tag names. |
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.
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:
( 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' )
On 401 prompt the user:
"Open https://servicegraph.co/profile/api-keys, create a key, and add
SERVICEGRAPH_API_KEY=vk_…to.env.localhere (or export it). Tell me when done. Please don't paste the key into chat."
Retry after the user signals ready.
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).
Engineering-flavored examples (validate yours with /check):
industry:engineering_services service_provided:civil-engineering state:FL transportation
industry:engineering_services service_provided:structural-engineering high-rise
industry:engineering_services service_provided:mep-engineering hospital
industry:engineering_services service_provided:mechanical-engineering hvac industrial
industry:engineering_services service_provided:environmental-engineering remediation
industry:engineering_services service_provided:geotechnical-engineering state:CA
industry:engineering_services service_provided:civil-engineering@high has:clutch
industry:engineering_services service_provided:electrical-engineering manufacturing
Sub-discipline → tag mapping (verify exact names via /fields;
~23 sub-tags so this isn't exhaustive):
| User asks for | Use |
|---|---|
| Civil engineering / sitework / transportation | service_provided:civil-engineering |
| Structural engineering | service_provided:structural-engineering |
| MEP (mechanical/electrical/plumbing) | service_provided:mep-engineering |
| Mechanical / HVAC | service_provided:mechanical-engineering |
| Electrical engineering | service_provided:electrical-engineering |
| Geotechnical / soils / foundations | service_provided:geotechnical-engineering |
| Surveying / land surveys / mapping | service_provided:surveying-mapping (NOT surveying) |
| Transportation engineering | service_provided:transportation-engineering |
| Environmental / remediation | service_provided:environmental-engineering |
| Manufacturing / process | service_provided:manufacturing-engineering |
| Aerospace | service_provided:aerospace-engineering |
| Energy (oil/gas/renewables) | service_provided:energy-engineering |
| Industrial automation / controls | service_provided:industrial-automation |
| Materials testing | service_provided:materials-testing |
| Acoustic / vibration | service_provided:acoustic-engineering |
| Biomedical | service_provided:biomedical-engineering |
Verticals (hospital, high-rise, semiconductor, retail, datacenter) and credentials (PE-licensed, LEED, AICP) are keyword-only.
apexFirms are identified by their apex domain (aecom.com, not
www.aecom.com/about).
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:civil-engineering+state:FL+transportation&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"] }
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:structural-engineering+(high-rise OR commercial)&limit=10
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:mep-engineering+hospital&limit=10
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:mechanical-engineering+hvac+industrial&limit=10
User: "We're building a 10-story office and need a structural engineer to stamp the drawings."
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:structural-engineering+commercial&limit=10
PE-license details surface from the unlocked platforms map / firm
detail. If the user wants only PE-licensed firms, add pe as a keyword.
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:geotechnical-engineering+state:CA&limit=10
Avoid pinning narrow keywords like seismic on top — engineering
verticals tend to collapse below k=20 quickly. The full state pool
of ~20 geotechnical firms is more useful than a 2-firm pool after
keyword narrowing.
Engineering firms aren't reviewed like agencies; rating>=N collapses
civil/structural/MEP pools sharply. Prefer @high + size + geography
as the quality proxy instead of a rating gate:
GET /v1/datasets/pro_services/search?filter=industry:engineering_services+service_provided:civil-engineering@high+state:CA+-company_size_signal:solo&limit=10
If the user insists on rated firms, add has:clutch (more lenient
than rating>=4).
User pastes 8–20 engineering firm domains:
GET /v1/datasets/pro_services/:apex per domain — free brief
(404 = not in catalog, no charge). A 404 often means the domain
is a software firm tagged industry:it_services instead of real
engineering.POST /unlocks = 10×N credits,
atomic, detail returned.industry:engineering_services. Without it, civil-engineering / mep-engineering / electrical-engineering keywords could leak into other industries (architecture firms sometimes list MEP coordination as a sub-service).engineering_services, not engineering. The literal pin industry:engineering returns zero results. Same drift logic for surveying-mapping (not surveying).find-software-developer. Real engineering is for buildings, infrastructure, energy, manufacturing — not for SaaS apps.rating>=N collapses pools below k=20. Use @high evidence + size + geography as the quality proxy.seismic on top of a CA geotech filter yields only ~2 firms vs ~20 without it. Drop narrowing keywords for default-required verticals.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.was_cached:true).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. |
| 400 | field_not_in_dataset | Drop the disallowed field. |
| 400 | invalid_apex | Re-normalize. |
| 401 | unauthorized / invalid_audience | Re-prompt for fresh vk_…. |
| 402 | insufficient_credits | needed and balance; nothing charged. |
| 404 | not_found / not_in_dataset | Skip; not charged. |
| 429 | rate_limited | Honor Retry-After. |
User: "Three civil engineering firms in Florida focused on transportation infrastructure, ideally with PE-licensed engineers."
GET /v1/datasets/pro_services/fields?include_values=1
GET /v1/datasets/pro_services/check?filter=industry:engineering_services+service_provided:civil-engineering+state:FL+transportation+pe
GET /v1/datasets/pro_services/search?filter=...&limit=10
# Present briefs. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
{ "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
GET /v1/me/credits
npx claudepluginhub nostrband/servicegraph --plugin servicegraphQueries the ServiceGraph API to find, shortlist, vet, and enrich US professional-services firms (law, marketing, consulting, accounting, IT services, architecture, engineering, HR, PR, design) by industry, service, location, size, and ratings.
Finds company and contact data from 150M+ companies and 800M+ professionals for lead generation, prospect research, and talent identification.
Discovers businesses by type and geography using Nimble WSAs. Supports audit mode to compare existing lists (Google Sheet, CSV, inline) against fresh discovery.