freehire Search Skill
Search tech job listings across many markets through freehire.me's public aggregator API — no keys, no signup, runs on your machine.
Code makes only public, unauthenticated GET requests to the freehire.me API with zero runtime dependencies; Bash permissions are scoped to a single CLI path; no credential handling, no writes, no covert data flows; graceful error paths and a swappable FREEHIRE_API_URL source. Deductions: performs external network calls against a third-party hosted service with no SLA, whose server-side behavior cannot be verified statically; no explicit rollback/isolation mechanism.
CLI is self-consistent with strict flag validation (rejects unknown flags, fractional/zero numerics), uniform stderr JSON errors with exit code 1; the repo ships offline mock tests covering flag validation, search/detail paths, 404 and network-failure branches, and CI claims typechecks and mock tests. Deductions: static review executes nothing, CI coverage of this skill is only partially visible in the truncated workflow file, and live API behavior (429 retries, agent endpoint) is not independently reproduced.
Triggers are explicit, boundaries are honest (tech-first scoping, non-tech coverage declared immature), inputs/outputs/partial-data semantics documented. Deductions: no Chinese-language support; core function depends entirely on the overseas freehire.me service with no stated mainland-China reachability or fallback, a material environment risk.
Well-layered SKILL.md (scope, dependency, commands, examples, output schemas, partial-data semantics), README, package. with version 1.0.0, MIT license; best-effort/no-SLA risk honestly disclosed. Deductions: no standalone changelog; maintenance responsibility and update path rest on repo-level governance rather than an explicit skill-level commitment; publisher identity unverified.
The claimed core task (multi-market tech job search plus single-posting detail) has complete paths, structured directly usable output, clear marginal value over manual browsing, and token-cost optimization (--no-description). Deductions: no executed verification; no third-party evidence of representative outputs; effectiveness hinges on a no-SLA personal hosted service remaining available.
Auditable primary material is present: source code, offline mock tests, CI workflows, and dated verification notes (e.g. live API behavior checked 2026-08-19). Deductions: static mode cannot independently reproduce conclusions; no multiple independent corroboration sources; the author's 'verified live' claims are accepted only as author assertions.
- Core function depends entirely on the overseas hosted service freehire.me (a personal project, best-effort, no SLA); mainland-China reachability is undeclared, and an outage disables this source.
- This is a static source review only; nothing was executed. Live API behavior (429 retries, agent endpoint, include_description parameter) rests on author claims.
- Non-tech job coverage is declared immature; scope triggers to technical/engineering roles or filtering may be unreliable.
- Aggregated listings may be incomplete or stale (regions/countries may be unresolved, as documented); verify against the original posting before acting.
- Publisher is unverified; the CLI makes outbound network requests — confirm reachability in your own network environment.
What does this skill do, and when should you use it?
freehire-search is a job-portal search skill inside the MadsLorentzen/ai-job-search repository that queries live software, data, engineering, DevOps, and remote job listings via freehire.me's public JSON API. freehire.me aggregates postings from ~50 ATS platforms into one normalized schema, so results come back structured (skills, seniority, region facets) instead of scraped from markup. The skill has zero runtime dependencies and runs with just Bun. The freehire backend itself is an open-source, MIT-licensed project you can self-host, switchable via a single environment variable.
Runs a Bun CLI that calls freehire.me's /api/v1/agent/jobs/search and job-detail endpoints. The search command supports keyword queries plus facet filters (--region, --country, --city, --seniority, --category, --skill, --remote, --jobage, and more), and each search result already carries the full posting description, so no per-hit follow-up requests are needed. The detail command looks up one posting by slug or URL, including closed postings. Output formats are , table, and plain; errors are written to stderr as structured JSON with a non-zero exit code. The API retries 429/5xx with exponential backoff.
- A job seeker who wants to search remote developer roles across multiple countries and markets in a single request that already includes full descriptions
- A user who wants precise filtering of tech jobs by seniority (e.g. senior), category (e.g. devops), or canonical skills (e.g. go, kubernetes)
- Someone with a freehire slug or link for a specific posting — including one already closed — who needs its full details
- A fork-owner of ai-job-search who wants /scrape to include a no-login, no-API-key job source for international markets
- A privacy-minded user who prefers pointing the CLI at a self-hosted freehire instance via the FREEHIRE_API_URL environment variable
What are this skill's strengths and limitations?
- Zero runtime dependencies — just Bun, no API key or authentication
- Search results include the full posting description, replacing 1+N scrape requests with one
- Structured JSON output (skills, seniority, category, region facets) rather than parsed markup
- Country-agnostic: facet flags (--region, --country) adapt it to any market out of the box
- Backend is open-source and self-hostable; FREEHIRE_API_URL is a one-line switch, and outages degrade gracefully instead of breaking the workflow
- Depends on freehire.me, a personal project with no formal SLA that can go down
- Faceted filtering (skills, categories, seniority) is tuned tech-first — not reliable for general, non-technical job coverage
- Facets can be incomplete: jobs whose region/country wasn't resolved are silently dropped by --region filters
- Self-hosting a full, continuously-fresh mirror (millions of postings) is resource-heavy
- The skill does search and detail only; application tracking and tailoring are handled by other skills in the repo, not this one
How do you install this skill?
The skill ships inside the MIT-licensed MadsLorentzen/ai-job-search repository at .agents/skills/freehire-search/. Fork and clone it: gh repo fork MadsLorentzen/ai-job-search --clone. Because the skill has zero runtime dependencies, bun install is optional (it only pulls TypeScript dev types); to install anyway: cd .agents/skills/freehire-search/cli && bun install. Bun (https://bun.sh) must be on your machine. The surrounding repo also requires the Claude Code CLI.
How do you use this skill?
Run from the repo root, e.g.: bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table. Other examples: --remote remote --region eu for remote EU roles; --category devops --country DE --jobage 14 for recent German DevOps jobs; detail golang-zensar-2bxu6dxm for one posting. Discover live facet vocabulary at https://freehire.me/api/v1/jobs/facets — never invent facet values. Inside Claude Code, the skill is invoked by the /scrape workflow via trigger phrases like "find a tech job" or "remote developer jobs".
How does this skill compare with similar options?
The repo positions it as a country-agnostic counterpart to linkedin-search: linkedin-search hits LinkedIn's public unauthenticated endpoints and takes a free-text location but is personal-use-only due to LinkedIn's ToS, while freehire-search uses an aggregator's public REST API with structured facets and cleaner terms. Unlike the repo's four Danish HTML-scraping portals (Jobindex, Jobnet, etc.), this skill parses no HTML.