agentleFS
amikaiamikai/openings-mcp/.agents/skills/verify-companies/SKILL.md

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.

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
  1. Very specific:

    Keep the default 300s --timeout: the largest full-dump boards (e.g.

    line 34
  2. Very specific:

    No working careers page or unsupported ATS → remove the entry.

    line 61
  3. Very specific:

    Commit per the roster: convention in AGENTS.md.

    line 65

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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.

  1. 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.
  2. Move the entries into the provider's companies.yaml (same YAML shape) and delete them from unverified/<provider>.yaml.
  3. go run ./cmd/verify-companies --provider <name> — rosters are go:embed'd, so go run picks the additions up. Drop entries that ERROR (re-check stale vs transient as in the audit).
  4. go test ./... — ats.NewRegistry requires every display name and slug to be unique within the promoting provider's own roster; move a collision there back to unverified/ 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 — NewRegistry fails if it collides. A collision with a different provider's roster is otherwise allowed and expected as rosters grow — it surfaces as a red TestCompanyCollisionReport. Regenerate cmd/openings-mcp/testdata/company_collisions.txt with go test ./cmd/openings-mcp -run TestCompanyCollisionReport -update and show its diff in the PR.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.