Skip to content

moonlight-lupin/agent-skills / research/people-enrichment

people-enrichment

Verified

Use when the user has a list of names or companies and wants their job, employer, work history, LinkedIn URLs or company profiles looked up, or wants to find people or companies matching criteria — trigger on phrases like "enrich these contacts", "find their LinkedIn", "look up these people", "who works at X", "find directors at Y", "enrich these companies", or "get firmographics for". Enrich and search People Data Labs (PDL) Person and Company data, writing results to .xlsx. Five operations: enrich named PEOPLE into a profile, employment history and LinkedIn URL; IDENTIFY an ambiguous person as several scored candidates; SEARCH people by criteria (company, title, location); enrich COMPANIES into firmographics (industry, size, employees, HQ, founded, LinkedIn); and SEARCH companies by criteria. Do not scrape LinkedIn directly — this uses a licensed data aggregator (PDL) instead, for legal and reliability reasons.

FileKindSize
README.mdmarkdown2.0 KB
SKILL.mdskill md10.9 KB
references/sample_companies.csvother67 B
references/sample_input.csvother117 B
requirements.txtmanifest93 B
scripts/email_list.pyscript10.0 KB
scripts/enrich.pyscript26.9 KB
tests/__init__.pyscript0 B
tests/test_email_list.pyscript4.1 KB
tests/test_enrich.pyscript24.6 KB
---
name: people-enrichment
description: "Use when the user has a list of names or companies and wants their job, employer, work history, LinkedIn URLs or company profiles looked up, or wants to find people or companies matching criteria — trigger on phrases like \"enrich these contacts\", \"find their LinkedIn\", \"look up these people\", \"who works at X\", \"find directors at Y\", \"enrich these companies\", or \"get firmographics for\". Enrich and search People Data Labs (PDL) Person and Company data, writing results to .xlsx. Five operations: enrich named PEOPLE into a profile, employment history and LinkedIn URL; IDENTIFY an ambiguous person as several scored candidates; SEARCH people by criteria (company, title, location); enrich COMPANIES into firmographics (industry, size, employees, HQ, founded, LinkedIn); and SEARCH companies by criteria. Do not scrape LinkedIn directly — this uses a licensed data aggregator (PDL) instead, for legal and reliability reasons."
license: MIT
metadata:
  version: 1.1.0
  author: moonlight-lupin
  platforms: [linux, macos, windows]
---

# People Enrichment & Search (People Data Labs)

One script, `scripts/enrich.py`, with five subcommands over PDL's Person and Company datasets. All share the same API-key handling, the boolean-PII contact logic, status flags, `.xlsx` styling, and a `--dry-run` preflight mode.

| Subcommand | Input | Output | Billing |
| --- | --- | --- | --- |
| `person-enrich` | list of named people | profile + work history | 1 credit / match |
| `person-identify` | list of people (ambiguous) | several scored candidates each | per PDL identify terms |
| `person-search` | criteria flags | a list of matching people | 1 credit / record returned |
| `company-enrich` | list of companies | firmographics | 1 credit / match |
| `company-search` | criteria flags | a list of matching companies | 1 credit / record returned |

The two *search* commands return data per *result*, so cost scales with `--size`. Always state the rough cost before a large search and keep `--size` modest unless the user asks for more (max 100 per request).

## Scope and routing

Use this skill when the user wants PDL person/company enrichment or search for a legitimate, proportionate purpose. Do **not** use it to scrape LinkedIn directly, to compile an intrusive profile, or where a host environment mandates a different data provider.

## Why People Data Labs, not a LinkedIn scraper

Scraping LinkedIn is fragile and legally risky. This skill uses PDL as a licensed aggregator rather than live LinkedIn scraping. If the user insists on live scraping, explain the trade-off rather than building a scraper.

## The API key

`scripts/enrich.py` needs a PDL key, resolved at runtime in this order: `PDL_API_KEY` env var → `.env` in the cwd → `.env` next to the script. **The key must never be written into this skill or any script.** If absent, live commands exit with instructions. `--dry-run` and `--self-test` do not require a key.

Create the `.env` only locally:

```bash
echo 'PDL_API_KEY=their_key_here' > .env
```

Treat `.env` as a secret: don't print, commit, or upload it. `--self-test` runs offline (canned data, no key) and writes sample people + company sheets so the user can see the output format before spending credits.

## Dry-run preflight

Before spending credits, especially on larger files or searches, run the same command with `--dry-run`:

```bash
python scripts/enrich.py person-enrich --input people.csv --output out.xlsx --dry-run
python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25 --dry-run
python scripts/enrich.py company-search --industry "real estate" --country singapore --size 50 --dry-run
```

Dry-run validates the input/search, prints the planned output, and estimates maximum credits without requiring `PDL_API_KEY`, calling PDL, or writing `.xlsx` output.

## Contact fields and the free plan

On the free plan, PDL returns PII fields (`emails`, `phone_numbers`) as a boolean, not the value: `true` = a contact exists but is paywalled, `false` = none on file. The people sheets surface this in **Email status** / **Phone status** columns: `included` (real value present, Pro plans), `exists - upgrade to view` (paywalled but present), `none on file`, or `unknown`.

## The five commands

**person-enrich** — one-to-one match named people.

```bash
python scripts/enrich.py person-enrich --input people.csv --output out.xlsx
```

Recognised input columns (case/space-insensitive): name/full name, first name, last name, company/employer, title, location, email, linkedin/profile. More context per row = higher match rate.

**person-identify** — when a single enrich is ambiguous, get the candidate set.

```bash
python scripts/enrich.py person-identify --input people.csv --max-candidates 5
```

Same input as enrich. Output has multiple rows per input person, each a scored candidate (Match score column), so the user can pick the right one.

**person-search** — find people by criteria, no name list needed.

```bash
python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25
```

Flags: `--company --title --location --country --industry --name`, plus `--size` (1–100), `--dataset` (default all), and `--sql` to pass a raw PDL SQL query for full control. Flags are combined with AND.

**company-enrich** — match a list of companies to firmographics.

```bash
python scripts/enrich.py company-enrich --input companies.csv --output firms.xlsx
```

Recognised input columns: name/company, website/domain, ticker, linkedin/profile, location/country/region/locality. Needs at least one of name/website/ticker/profile per row.

**company-search** — find companies by criteria.

```bash
python scripts/enrich.py company-search --industry "real estate" --country singapore --min-employees 50 --size 50
```

Flags: `--name --industry --country --locality --tag --min-employees`, plus `--size` and `--sql`.

## Enrich a list of email addresses — triage first, one lookup per company, people last

For a list that is mostly addresses (an event sign-up sheet, a CRM export, a business-card scan),
`scripts/email_list.py` keeps the lookups to what the list actually needs:

```bash
python scripts/email_list.py triage --input emails.csv --out-dir work --exclude-domain yourco.example
python scripts/enrich.py company-enrich --input work/companies.csv --output work/companies.xlsx
python scripts/enrich.py person-enrich  --input work/people.csv    --output work/people.xlsx   # only if names/titles are needed
python scripts/email_list.py merge --dir work --output enriched_list.xlsx
```

1. **Triage (free, offline)** sorts every unique address into webmail (never looked up — no
   company data, and private), shared mailbox (`info@`, `sales@` …; company lookup only),
   personal work address, invalid, or excluded (`--exclude-domain`, e.g. your own organisation).
2. **One company lookup per domain**, not per address — `companies.csv` has one row per domain.
3. **People last, and only if needed.** Firmographics alone need no person lookup; run
   `people.csv` only when names or titles matter. Quote the credit count (`--dry-run`) first.
4. **Merge** writes one row per address with an outcome — person, company only, webmail, not
   found, excluded — and a check column: matches below the confidence floor, and a person whose
   current company differs from the address's domain (they may have moved). Blanks stay blank.

Adapted from monid's guide to email-list enrichment (triage, dedupe by domain, then pay).

## Reviewing output with the user

People sheets have two tabs: **People** (one row per person, status colour-coded) and **Employment history** (one row per past role). Company sheets have a single **Companies** tab. The **Status** column is the first thing to check: `matched` (green), `needs_review` (amber), `no_match` (red), `error` (orange). Call out the amber/red rows explicitly so the user knows what to double-check.

## Tuning matches

`--min-likelihood N` (1–10) is the confidence floor for the enrich/identify commands. Raise it (6–8) when names/companies are common and you'd rather miss than mis-match; lower it when you have rich context and want coverage. Company enrichment is most reliable with a website/domain; person enrichment with a company or email alongside the name.

## Swapping providers later

The PDL-specific pieces are the `*_params` builders, `pdl_request`, and the `parse_person` / `parse_company` mappers. To support another provider, implement those against its API and keep the same record dict shape; input parsing, status logic, SQL/flag handling, dry-run summaries, and `.xlsx` writing stay as is.

## Principles

- **Drafts, not advice** — output is a research aid for a person to review, not a determination.
- **Never invent** — surface only what PDL returns; mark `no_match`/`needs_review` honestly rather than guessing an identity.
- **Deterministic where it counts** — input parsing, status logic, dry-run estimates and `.xlsx` writing are deterministic.
- **Honesty and calibration** — flag low-confidence matches and show the rough credit cost up front.
- **Workspace hygiene** — write outputs where the user expects; never write the API key to disk in the skill.

## Data handling

**PDL is a third party and enrichment sends the real name/company to it** — it cannot be tokenised, because the name *is* the lookup. Treat the `.env` / `PDL_API_KEY` as a secret: never print, commit or upload it. For people, confirm a legitimate and proportionate purpose and collect only fields relevant to that purpose.

## Pitfalls

1. **Free plan hides contact values** — emails/phones come back as booleans; read the status columns.
2. **Shared mailboxes are not people** — `info@`, `sales@`, `ir@`-style addresses are dropped from a person's email list (`is_role_address`).
3. **Search cost scales with `--size`** — quote the rough credit cost and keep `--size` modest.
4. **Common names mis-match** — raise `--min-likelihood` or add context columns (company/email).
5. **Never commit `.env`** — the key is a secret; `--self-test` and `--dry-run` need no key.
6. **Dry-run is an estimate** — actual billing follows PDL's endpoint terms and returned records/matches.

## Verification checklist

- [ ] Legitimate, proportionate purpose confirmed for any person enrichment/search.
- [ ] `--dry-run` used for large files or searches to validate scope and estimate credits.
- [ ] `PDL_API_KEY` available via env or `.env` for live runs (never written into the skill).
- [ ] Rough credit cost stated before any large search.
- [ ] Amber/red status rows flagged to the user.
- [ ] For an email list: triage run first; webmail never sent; one company lookup per domain; person lookups only if needed.
- [ ] `.env` not printed/committed.

## Requirements

- Python 3.8+
- `pip install openpyxl` (HTTP uses the stdlib `urllib` — no `requests` needed)
- `PDL_API_KEY` (env var or `.env`) for live API calls; get one at https://www.peopledatalabs.com
- Network access to the PDL API. `--self-test` and `--dry-run` run fully offline.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall