verify-companies
Skill106 starsChanged 3 months agoMITView on GitHub
Use when auditing the curated ATS rosters for stale entries, pruning dead boards or tenants, promoting candidates from unverified/ into internal/provider/*/companies.yaml, or when search_jobs_by_company errors on a company that used to work.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- discover-companiesSkill
- integrate-new-providerSkill
- releaseSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Keep the default 300s --timeout: the largest full-dump boards (e.g.
- Very specific: line 61
No working careers page or unsupported ATS → remove the entry.
- Very specific: line 65
Commit per the roster: convention in AGENTS.md.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Verify Companies
Overview
cmd/verify-companies sweeps every curated companies.yaml entry
through the real internal/ats adapter path — the same code the MCP server serves —
and reports each entry as OK with its total job count, or ERROR with the
error message. Each successful search is followed by one Detail probe on
a sampled job. Two workflows build on it: audit (find and prune
stale roster entries) and promotion (move unverified/<provider>.yaml
candidates into the curated roster).
The sweep
go run ./cmd/verify-companies [--provider ashby,greenhouse,lever,workday] \
[--format text|json] [--concurrency N] [--timeout D]- Any Search failure is ERROR — a stale identifier's 404 and a transient timeout or 5xx look the same at the status level; the detail column tells them apart.
- DETAIL_ERROR means the search succeeded but the Detail probe on a sampled job failed — usually a detail-template divergence in the adapter (issue #196's shape), not a stale roster entry. The fix is adapter code, not the roster.
zero-jobin the summary is informational: board live, no current openings. Not a failure. Zero-job boards get no Detail probe.- Keep the default 300s
--timeout: the largest full-dump boards (e.g. Palantir, Veeva on lever) take minutes to download, and 60s produced false ERRORs. - Recruitee is auto-capped at 2 concurrent workers inside
verify-companies(even when--concurrencyis higher): its public API rate-limits hard (HTTP 429) around the default pool size. - Exits non-zero on any ERROR or DETAIL_ERROR, so it doubles as a CI check.
Audit workflow
- Sweep, scoped with
--providerwhen you already know the target;--format jsonwhen you'll process the results. - Re-run the failures once before touching the roster — transient timeouts and 5xx clear on retry; stale identifiers (404, unknown board) don't. Read the detail column, don't just count statuses.
- For each confirmed-stale ERROR and each OK entry with 10 or fewer
jobs, web-search the company's current careers page
(
<company> careers) — a dead or near-empty board is often a leftover after the company moved to another ATS. Then, by what the careers URL shows (adapter host shapes:careersHostPatternsByAdapter,internal/ats/registry.go):- Another supported adapter's host → the company migrated. Move the
entry to that provider's
companies.yaml, slug taken from the URL, and verify with--provider <new>. - Same provider, different slug → fix the slug.
- Same provider, same slug → small company; leave it.
- No working careers page or unsupported ATS → remove the entry. If
only the display name is in doubt, move it to
unverified/<provider>.yaml.
- Another supported adapter's host → the company migrated. Move the
entry to that provider's
go test ./...— registry tests catch roster mistakes.- Commit per the
roster:convention in AGENTS.md.
Promotion workflow
unverified/ entries have a live-verified board/tenant but an
unconfirmed display name — often just the slug. The directory is not
go:embed'd, so it never affects the built binary.
- Confirm the real display name from an authoritative source (the company's own site or careers page). Never promote a guessed name; that's the whole reason the entry is quarantined.
- Move the entries into the provider's
companies.yaml(same YAML shape) and delete them fromunverified/<provider>.yaml. go run ./cmd/verify-companies --provider <name>— rosters are go:embed'd, sogo runpicks the additions up. Drop entries that ERROR (re-check stale vs transient as in the audit).go test ./...—ats.NewRegistryrequires every display name and slug to be unique within the promoting provider's own roster; move a collision there back tounverified/for a human to sort out rather than inventing a disambiguated name. When the adapter cannot render a careers URL for an entry, its display name is the only disambiguation key left, so keep that name unique against every other entry's name and slug anywhere —NewRegistryfails if it collides. A collision with a different provider's roster is otherwise allowed and expected as rosters grow — it surfaces as a redTestCompanyCollisionReport. Regeneratecmd/openings-mcp/testdata/company_collisions.txtwithgo test ./cmd/openings-mcp -run TestCompanyCollisionReport -updateand show its diff in the PR.- One roster per PR, one
roster:commit (AGENTS.md).
Common mistakes
- Pruning on a transient error — a timeout on a huge full-dump board is not a stale entry. Retry first.
- Removing a stale entry without checking for an ATS migration — when the company moved providers, the fix is a move, not a removal.
- Workday roster rows sharing one tenant:
WorkdayAdapter.Roster()dedupes by tenant and serves only the first row, so the rest sit in the file looking valid while being unreachable. One row per tenant. - Promoting entries whose display name was never confirmed.
- Batching several providers' rosters into one PR — AGENTS.md wants one roster per PR.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

