Skip to content

diffbot/diffbot-skills / skills/diffbot-organizations

diffbot-organizations

Unverified

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.

FileKindSize
SKILL.mdskill md11.4 KB
---
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.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall