diffbot/diffbot-skills / skills/diffbot-organizations
diffbot-organizations
UnverifiedCompany and organization structured search over the Diffbot Knowledge Graph. Prefer for prospect lists, market maps, competitor sets, and firmographic facts on a market or a named company, plus similarTo lookalike lists. Filter by industry, location, headcount, revenue, founding date, public status, founder, investor, acquirer, or parent company. MUST USE skill when the answer is a list of companies or involves structured company data. Rows are companies, not deals. Triggers on: find companies, list companies, search companies, competitors of, companies like, startups in, firms, vendors of, suppliers of, customers of, market map, prospect list, companies by industry, look up.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
SKILL.md
View on GitHub---
name: diffbot-organizations
description: "Company and organization structured search over the Diffbot Knowledge Graph. Prefer for prospect lists, market maps, competitor sets, and firmographic facts on a market or a named company, plus similarTo lookalike lists. Filter by industry, location, headcount, revenue, founding date, public status, founder, investor, acquirer, or parent company. MUST USE skill when the answer is a list of companies or involves structured company data. Rows are companies, not deals. Triggers on: find companies, list companies, search companies, competitors of, companies like, startups in, firms, vendors of, suppliers of, customers of, market map, prospect list, companies by industry, look up."
---
# Diffbot Organization Search
Find organizations in the Diffbot Knowledge Graph. This is `type:Organization` DQL with the company-research levers pre-selected: industry taxonomy, headquarters vs. offices, headcount and revenue bands, funding, and ownership.
**The organizations/deals boundary is the row shape.** If the rows the user wants are companies, this skill owns it — including "everything Microsoft acquired", which is a list of target companies. If the rows are transactions, investments, or deals, hand off to `/diffbot-deals`. Both filter on the same `acquiredBy` and `investments` fields; what differs is what ends up in the table.
Sibling skills: `/diffbot-news` (articles), `/diffbot-places` (geography), `/diffbot-deals` (deals as rows). Use `/diffbot-dql` for people, products, or 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.1'
```
If it prints a version below 3.1.1, 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/` in the working directory. `db` creates that folder itself, so don't `mkdir`
it first. `db`, `jq`, and `cat` are not pre-approved — 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 — build the query
Every query starts `type:Organization`. Layer the clauses below.
#### Industry — start here
`categories.name` is almost always the best first filter. Look up the exact string before using it; the taxonomy is title-cased and often plural (`"Semiconductor Companies"`, `"Artificial Intelligence Software"`).
```
~/.diffbot/venv/bin/db dql ontology taxonomy OrganizationCategory <regex>
```
```
type:Organization categories.name:"Semiconductor Companies" isPublic:true
```
When no category fits the niche, fall back to **`descriptors`** — short free-text capability tags:
```
type:Organization descriptors:"GPU"
type:Organization descriptors:"mexican restaurant" near(type:Organization name:"Diffbot")
```
#### Location — singular is headquarters, plural is any office
| Use | Meaning |
| --- | --- |
| `location.city.name:"Berlin"` | **Headquartered** in Berlin — the primary location |
| `locations.city.name:"Berlin"` | Has *an* office in Berlin, HQ anywhere |
Prefer the singular form for "companies in X". The same split applies to `name`/`allNames`, `description`/`allDescriptions`, `homepageUri`/`allUris`.
`location` is a `Location` composite: `.city.name`, `.region.name`, `.country.name`, `.subregion.name`, `.metroArea.name`, `.street`, `.postalCode`, `.latitude`, `.longitude`.
#### Field reference
| Field | Type | Notes |
| --- | --- | --- |
| `name` / `fullName` | String | Add `strict:` for exact match: `strict:name:"Apple Inc"` |
| `categories` | list | `categories.name` — OrganizationCategory taxonomy |
| `descriptors` | list of String | Free-text capability tags |
| `homepageUri` | URL | Primary domain |
| `nbEmployees` | Integer | Also `nbEmployeesMin`, `nbEmployeesMax`, `nbEmployeeRanges` |
| `revenue.value` / `.currency` | Amount | Also `yearlyRevenues`, `quarterlyRevenues` |
| `isPublic` | Boolean | |
| `ipo` | IPO composite | |
| `stock` | Stock composite | Ticker and exchange |
| `foundingDate` | DDate | `foundingDate>="2020-01-01"` |
| `ceo` | LinkedEntity (Person) | `ceo.name` |
| `founders` | list | `founders.name` |
| `investments` | list | `investments.investors.name`, `investments.series`, `investments.amount.value`, `investments.date` |
| `totalInvestment` | Amount | `totalInvestment.value>100000000` |
| `nbUniqueInvestors` | Integer | |
| `isAcquired` | Boolean | |
| `acquiredBy` | list | `acquiredBy.name` (acquirer), `acquiredBy.amount.value`, `acquiredBy.date` |
| `location` / `locations` | Location | See above |
| `nbLocations` | Integer | |
#### Matching a company by name — use `strict:`
`name:"…"` is a **contains** match, and company names are short and repetitive, so it
over-matches badly:
| Query | Hits |
| --- | --- |
| `type:Organization name:"Apple"` | 68,068 |
| `type:Organization strict:name:"Apple"` | 1,426 |
| `type:Organization strict:name:"Apple Inc."` | 1 |
When the user names a specific company, reach for `strict:` first and fall back to the
contains form only if it returns nothing. When they mean a *category* of company
("apple growers"), contains is correct — but prefer `categories.name` or `descriptors`
for that.
`strict:` still leaves duplicates: the KG holds several records for large companies
(subsidiaries, regional entities, stale dupes). Sort by `nbEmployees` or `importance`
and take the top row when you need "the" company.
#### `near` — companies within a radius of a place
Default radius 15km; override with `mi` or `km`. `near` resolves a single anchor
entity — if the inner query matches several, only the first is used.
```
type:Organization categories.name:"Semiconductor Companies" near(type:Place name:"Austin", 30mi)
type:Organization descriptors:"mexican restaurant" near(type:Organization name:"Diffbot")
```
Use this rather than `location.city.name` when the user says "near", "around", or
"within X miles" — city-name matching misses the surrounding metro.
#### `similarTo` — find companies like this one
Organization-only. Give it an anchor and it returns a ranked list of similar companies — the right tool for "competitors of X", "companies like X", or building a lookalike list.
```
type:Organization similarTo(name:"OpenAI")
type:Organization similarTo(type:Organization homepageUri:"walmart.com")
```
The anchor is a subquery: `name:"…"` is the short form, or use a fuller one like `type:Organization homepageUri:"…"` when the name is ambiguous.
**Other clauses compose and narrow within the similarity search** — they are not a post-filter on the top N, so adding a filter surfaces companies deeper in the ranking rather than just deleting rows:
```
type:Organization similarTo(name:"OpenAI") location.country.name:"United States"
type:Organization similarTo(name:"OpenAI") isPublic:true
```
**It behaves differently from a normal query in two ways:**
- It returns *exactly* `--size` results, ranked by similarity. The `hits` field mirrors the size you asked for, so there is no meaningful total — asking for more results just goes further down the ranking.
- **`db dql probe` cannot validate it.** Probe runs at `size=0`, and `similarTo` at `size=0` returns 0 — which looks like "no matches" but means nothing. Skip Step 3 for `similarTo` queries and validate with a small export (`--size 10`) instead.
#### Subqueries — co-constraining nested fields
Use `{}` when two conditions must hold on the *same* nested object:
```
type:Organization investments.{series:"Series A" date>="2026-01-01"}
```
Without `{}` those are independent — an org with *any* Series A and *any* 2026 round would match, even if they are different rounds. `{}` only works on composite-typed list fields.
#### Worked examples
```
type:Organization categories.name:"Semiconductor Companies" isPublic:true
type:Organization categories.name:"Artificial Intelligence Software" location.city.name:"San Francisco"
type:Organization investments.investors.name:"Sequoia Capital"
type:Organization nbEmployees>1000 revenue.value>1000000000
type:Organization isAcquired:true acquiredBy.name:"Microsoft"
type:Organization categories.name:"Artificial Intelligence Software" investments.{amount.value>50000000 date>="2026-01-01"}
type:Organization range:nbEmployees:10-100 location.country.name:"Germany" descriptors:"SaaS"
type:Organization similarTo(name:"OpenAI") location.country.name:"United States"
```
**Distribution questions** ("what industries dominate Berlin startups?") are facets, not row lists:
```
~/.diffbot/venv/bin/db dql export 'type:Organization location.city.name:"Berlin" facet:categories.name' \
--out .diffbot/tmp/facet.json --format json --size 25
```
Facets require `--size` ≥ 1 (`--size 0` errors), and `--size` sets the **number of buckets** returned, not rows.
### Step 3 — probe before committing
```
~/.diffbot/venv/bin/db dql probe \
'type:Organization descriptors:"GPU" location.country.name:"United States"' \
'type:Organization categories.name:"Semiconductor Companies" location.country.name:"United States"' \
'type:Organization categories.name:"Semiconductor Companies" location.country.name:"United States" isPublic:true'
```
Zero hits usually means a mistyped category — re-check with `ontology taxonomy`. Note that `probe` fails the whole batch if any one variant is rejected by the API, so fix the bad clause and re-run.
**Do not probe `similarTo` queries** — probe runs at `size=0`, where `similarTo` always reports 0 regardless of how good the query is. Validate those with a small export instead.
### Step 4 — export and display
CSV for direct display:
```
~/.diffbot/venv/bin/db dql export "<DQL>" --out .diffbot/tmp/orgs.csv \
--spec "name,Company;descriptors,Description;nbEmployees,Employees;revenue.value,Revenue;location.city.name,City;location.country.name,Country;homepageUri,Website;isPublic,Public" \
--size 50
```
JSON when results feed further analysis:
```
~/.diffbot/venv/bin/db dql export "<DQL>" --out .diffbot/tmp/orgs.json --format json --size 50
```
`--spec` renders only the **primary** value of list/composite fields — one investor, one location. Export JSON if the user needs full lists.
**Display**
1. Render a markdown table sized to the question — company, one-line descriptor, headcount, HQ, website.
2. Numeric amounts come back in scientific notation (`1.0E8`); format them as `$100M` for the user.
3. Print the final DQL in a plain code block.
4. Tell the user the saved file path, and offer more rows (`--size N`, `--from K`) or a refinement.
For `similarTo` results, present them as a ranked list and say what the anchor was — the ordering is the answer, and there is no total count to report.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |