openings-mcp: Skill for Claude Code

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-job in 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 --concurrency is 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

1. Sweep, scoped with --provider when you already know the target; --format json when you'll process the results.
2. 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.
3. 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.
4. go test ./... — registry tests catch roster mistakes.
5. Commit per the roster: convention in AGENTS.md.