diffbot-people skill

Diffbot People Search

Find people in the Diffbot Knowledge Graph. This is type:Person DQL with the people-research levers pre-selected: employment history, employer industry, education, skills, and location.

Coverage is limited to people with a public online presence — see the note at the end before reporting an empty or partial result.

Row shape decides the skill. If the rows are people, this skill owns it — including "who runs Nvidia". If the rows are companies ("companies whose CEO is a woman"), use /diffbot-organizations. Sibling skills: /diffbot-news, /diffbot-places, /diffbot-deals. Use /diffbot-dql for anything outside these shapes.

Workflow

Step 1 — check the CLI, then db dql init

~/.diffbot/venv/bin/db --version
~/.diffbot/venv/bin/db dql init

The db CLI is a one-time user install at ~/.diffbot/venv/bin/db, the same way gh or wrangler is — this skill never installs, upgrades, or uninstalls it. If --version fails with No such file or directory, stop and show the user this line to run or approve themselves (it is deliberately not pre-approved):

python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.0'

If it prints a version below 3.1.0, fails with No such option '--version' (an old diffbot-python install, which predates the flag), or warns about the diffbot-python rename, point the user at Upgrading the db CLI in the plugin README and stop. Never run an install, upgrade, or uninstall line yourself.

Save output files under ~/.diffbot/tmp/. db creates that folder itself, so don't mkdir it first. Reading files there with the Read tool is pre-approved. jq, cat, and db are not — Claude will ask before running them.

init refreshes ~/.diffbot/ontology.json and verifies a token (DIFFBOT_API_TOKEN env var, else ~/.diffbot/credentials). If neither exists the user must run:

echo "DIFFBOT_API_TOKEN=YOUR_TOKEN_HERE" > ~/.diffbot/credentials && chmod 600 ~/.diffbot/credentials

Tokens: https://app.diffbot.com/get-started/. Never echo the token.

Step 2 — the subquery rule comes first

employments is a list of jobs. Conditions written separately are matched against different jobs, which silently inflates results. Co-constrain them with {}:

✗ type:Person employments.{title:"Chief Executive Officer" isCurrent:true} employments.employer.categories.name:"Semiconductor Companies"
✓ type:Person employments.{title:"Chief Executive Officer" isCurrent:true employer.categories.name:"Semiconductor Companies"}

Measured: 3,457 hits vs 399. The loose form matches anyone who was ever a CEO somewhere and also worked at some semiconductor company — a different job. Nearly 9 out of 10 of those rows are wrong.

Put every condition about one job inside one {}. The same applies to educations, colleagues, and locations.

Add isCurrent:true whenever the user means the present ("who runs X", "current CTO"); omit it for history ("everyone who has worked at X").

Step 3 — the levers

Employer industry resolves — this is the headline capability

employments.employer is a full Organization link, so you can filter people by their employer's industry, size, or location:

type:Person employments.{title:"Chief Technology Officer" isCurrent:true employer.categories.name:"Biotechnology Companies"}
type:Person employments.{isCurrent:true employer.location.country.name:"Germany" employer.nbEmployees>1000}

Look up category strings first — they are title-cased and usually plural: ~/.diffbot/venv/bin/db dql ontology taxonomy OrganizationCategory <regex>

(Contrast with /diffbot-deals, where investee is a bare LinkedEntity with no categories. The employer link is richer — the deals trap does not apply here.)

Field reference

Field	Type	Notes
name / allNames	String	nameDetail.firstName, .lastName, .nicknames
employments	list	.title, .employer.name, .isCurrent, .from, .to, .description, .location, .categories.name (EmploymentCategory taxonomy), .technologies.name
educations	list	.institution.name, .major.name, .degree.name, .isCurrent, .hasDroppedOut, .from, .to
skills	list	skills.name — free-form skill entities
location / locations	Location	Singular is primary residence; same HQ-vs-offices split as Organization
nationalities	list	nationalities.name
gender	enum	gender:"Female" works; gender.normalizedValue:"Female" is equivalent. Values: Male, Female, Transgender_male, Transgender_female, Bigender, Agender, Trigender, Other
age, birthDate, deathDate		birthPlace, deathPlace are Location composites
netWorth.value	Amount	See the caveat below
awards	list	awards.title, awards.date
colleagues	list	.colleague.name, .relationship, .isCurrent
parents, children, siblings, unions	list	Family graph
politicalAffiliation	list	Linked Organization
importance	Float	Prominence — the best general "most notable first" sort
wikipediaPageviews	Integer	Attention proxy, with quarter/year and growth variants
linkedInUri, twitterUri, githubUri, crunchbaseUri, homepageUri	URL
emailAddresses, phoneNumbers	list	Sparse

type:PersonInvestor (~57k) is a narrower type for angels and individual investors.

Leave the sort off unless the user asked for an ordering. The default ranking already bakes in relevance and prominence, and an explicit sort overrides it — usually for the worse. Measured: homepageUri:"openai.com" unsorted returns OpenAI, while revSortBy:nbEmployees returns "OpenAI for Developers"; anthropic.com unsorted returns Anthropic, sorted returns "Claude Builder Club".

Add a sort only when the ordering is the question — "largest cities by population", "most recent rounds", "biggest acquisitions". (Articles are the exception: see /diffbot-news, where sortBy:date is the default.)

For people specifically: strict:name:"Jensen Huang" unsorted returns the records in descending importance order already (97.2, then 13.6, then 10.1) — the Nvidia CEO first, without asking for it.

Worked examples

type:Person employments.{employer.name:"Nvidia" isCurrent:true}
type:Person employments.{title:"Chief Executive Officer" isCurrent:true employer.categories.name:"Semiconductor Companies"}
type:Person educations.{institution.name:"Stanford University" major.name:"Computer Science"}
type:Person skills.name:"Machine Learning" location.city.name:"San Francisco"
type:Person gender:"Female" employments.{title:"Chief Executive Officer" isCurrent:true}
type:Person nationalities.name:"France" netWorth.value>1000000000 revSortBy:netWorth.value

Step 4 — probe before committing

~/.diffbot/venv/bin/db dql probe \
  'type:Person employments.{employer.name:"Anthropic" isCurrent:true}' \
  'type:Person employments.{employer.name:"Anthropic" isCurrent:true title:"Engineer"}'

Compare the {} and non-{} forms when a query has two or more employment conditions. A large gap means the loose form is matching across different jobs and the subquery is required. probe fails the whole batch if any variant is rejected, so fix the bad clause and re-run.

Step 5 — export and display

~/.diffbot/venv/bin/db dql export "<DQL>" --out ~/.diffbot/tmp/people.csv \
  --spec "name,Name;employments.title,Title;employments.employer.name,Employer;location.city.name,City;linkedInUri,LinkedIn" \
  --size 50

Display

1. Render a markdown table — name, title, employer, location.
2. Print the final DQL in a plain code block, give the saved file path, and offer more rows (--size N, --from K) or a refinement.

Traps

• --spec renders the primary employment, not the matched one. This is the trap most likely to make you report something false. Querying Tesla's founders returns the right people but the CSV shows their current jobs:

  Name	Employer (as rendered)
  Elon Musk	Neuralink
  Martin Eberhard	INEVIT
  JB Straubel	QuantumScape

  All three genuinely co-founded Tesla; none of those employers is Tesla. Don't present the rendered employer as the matched one. Export JSON and pick the right entry:

  jq -r '.data[].entity | .name as $n | .employments[] | select(.employer.name|test("Tesla")) | "\($n)\t\(.title)\t\(.employer.name)"' ~/.diffbot/tmp/people.json
  

• descriptors is effectively unpopulated on Person (descriptors:"venture capitalist" → 0 hits), unlike Organization where it is a good fallback. Use employments.title, skills.name, or summary instead.

• netWorth has extreme outliers — the top of revSortBy:netWorth.value includes obviously bad values (a $96T record) and historical figures like Mansa Musa. Sanity-check the top rows before presenting, and prefer a bounded range.

• Titles are free text, and the abbreviation is not a substring of the long form. title:"Chief Executive Officer" → 521,798 current holders; adding the abbreviation, title:or("Chief Executive Officer","CEO") → 2,620,747. Five times as many, and dropping them is a silent under-count, not an error. Always or() the abbreviation with the spelled-out form for C-suite roles (CEO, CTO, CFO, COO, CIO), and probe both. Note this is the opposite of a field like investment.series, where "Series A" already contains "Series A-1" and or() changes nothing — or() earns its keep only when the spellings genuinely differ.

• Board membership is titled "Director", not "Board Member". At Nvidia, title:"Board Member" finds 5 people; title:or("Board Member","Board of Directors","Director") finds 904. Never answer a board question with the naive string — it under-counts by two orders of magnitude. ("Founder" is the happy opposite: it is a substring of "Co-Founder", so it catches both without or().)

• For the CEO or founders of one specific named company, don't scan Person — read the Organization. It is a curated field and far cleaner than title matching, which drags in same-named companies (a Person scan for Tesla founders surfaced the band Tesla's guitarist). Note get: is required — these fields are absent from the default payload:

  ~/.diffbot/venv/bin/db dql export 'type:Organization homepageUri:"tesla.com" get:name,ceo,founders' --out ~/.diffbot/tmp/f.json --format json --size 1
  

  Returns ceo=Elon Musk, founders=JB Straubel, Martin Eberhard, Ian Wright, Marc Tarpenning, Elon Musk.

  Match on homepageUri, not name, and do not sort. Both alternatives fail: strict:name:"Apple" never matches the real company (its canonical name is "Apple Inc."), and adding revSortBy:nbEmployees returns "OpenAI for Developers" for openai.com and "Claude Builder Club" for anthropic.com. The domain plus the default relevance ranking is correct for all of apple.com, tesla.com, openai.com, anthropic.com, airbnb.com, nvidia.com, and stripe.com.

  Use /diffbot-people when the rows are people matching a pattern; use this when you want one company's known leadership.

• Matching a specific person by name — use strict:. name:"…" is a contains match, so a common name pulls in every partial hit. strict:name:"Jensen Huang" pins it. Person records also duplicate, so expect several rows for one individual.

• Person records duplicate. Same-name rows with different employers may be distinct people or the same person twice — say which when it matters.

Coverage — public presence only

The Knowledge Graph is built from the public web, so this skill sees people who have a public professional footprint: company pages, bylines, filings, conference listings, profiles they chose to publish. It does not surface people who have not put themselves online, and it is not a people-finder.

Two things follow, and both change how you report results:

• Absence is not evidence. Zero hits means "not publicly published", not that the person doesn't exist, doesn't hold the role, or isn't employed there. Say which one you actually know. Never present an empty result as a factual negative about someone.
• Coverage is uneven, so counts are a floor and never a census. Executives, founders, academics, authors, and public figures are dense; individual contributors, private-company staff, and people outside English-language sources are sparse. "15,227 people at Nvidia" is who is publicly documented, not the headcount — use /diffbot-organizations and nbEmployees for that.

If a request is really about locating, profiling, or compiling a dossier on a private individual, this skill is the wrong tool and name matching is not a substitute. Say the KG covers public professional presence and stop there.