What does this skill do, and when should you use it?
freehire-search is a job-portal search skill inside the ai-job-search repository that queries live tech job listings through freehire.me's public JSON API. The aggregator normalizes postings from ~50 ATS platforms across many countries into one schema, so a single skill covers multiple markets and remote roles. The skill itself has zero runtime dependencies and runs with just Bun. It offers faceted filtering (skills, category, seniority, region), but those dictionaries are tuned tech-first, so triggers are scoped to software/data/engineering/DevOps roles. It doubles as the repo's country-agnostic worked example of querying a structured API instead of scraping HTML.
- Calls freehire.me's public /api/v1/agent/jobs/search endpoint for keyword search, with each result carrying its full description so no per-hit follow-up requests are needed
- Filters postings through structured facets: --region, --country, --city, --seniority, --category, --skill, --company, --remote, --jobage, and more
- Looks up a single posting by slug (or full URL) via the detail command, including closed postings
- Outputs / table / plain formats; JSON is the default and the only format carrying full descriptions
- Retries 429/5xx with exponential backoff and fails gracefully (non-zero exit, clear error) when the API is unreachable
- Honors the FREEHIRE_API_URL env var so pointing it at a self-hosted freehire instance is a one-line change
- A job seeker who wants to scan remote developer openings across many countries in one command instead of visiting each board
- A Claude Code user building their own job-search workflow who wants a key-free, structured tech-job source inside /scrape
- An engineer filtering by seniority (e.g. senior), category (e.g. devops), or skills (e.g. go, kubernetes)
- Someone tracking newly posted roles in a specific country over the last two weeks (--country DE --jobage 14)
- Anyone who has a shared freehire link — or a closed posting — and wants the full description retrieved by slug
- Users needing solid coverage of non-technical roles (marketing, admin, healthcare): freehire's faceted dictionaries are tech-first today, so non-tech coverage is still maturing
- Users who need LinkedIn or Danish boards (Jobindex, Jobnet, etc.) — those are covered by separate sibling skills in the repo
- Automated production systems requiring an availability SLA — freehire.me is a personal, best-effort hosted service
How do you install this skill?
- 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.
- Shell / CLI
- Network access
- Local filesystem
Bun (zero runtime dependencies beyond bun)
The skill ships with the MadsLorentzen/ai-job-search repository (fork it to get it):
gh repo fork MadsLorentzen/ai-job-search --clone
cd ai-job-search
cd .agents/skills/freehire-search/cli && bun installNote: the skill has zero runtime dependencies; bun install only pulls TypeScript dev types and can be skipped.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Find DevOps jobs in Germany posted in the last 14 days (equivalent to --category devops --country DE --jobage 14)
- Search fully remote React roles in the EU, show as a table
- Find senior backend engineer roles with each posting's full description
- Look up this freehire job posting: golang-zensar-2bxu6dxm
Trigger via phrases like "find a tech job", "are there any <tech role> jobs in <place>", or run the CLI directly (allowed-tools uses Claude Code's Bash permission syntax). Search:
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format tableFetch one posting's detail:
bun run .agents/skills/freehire-search/cli/src/cli.ts detail golang-zensar-2bxu6dxm --format plainKey points: search results already include full descriptions, so don't loop detail over search hits; geography is facet-based, not free text — discover live values via /api/v1/jobs/facets before filtering and never invent facet values; use --no-description for a cheap discovery pass and pull bodies with detail afterward; use --region none to match postings whose region wasn't resolved.
What are this skill's strengths and limitations?
- No signup, no API key, zero runtime dependencies — runs with just Bun
- ~50 ATS platforms aggregated into one schema; one skill covers many markets and remote roles
- Search results carry full descriptions, avoiding per-hit fetches
- The freehire backend is MIT-licensed and self-hostable; switching is a one-line env var
- Robust error handling: exponential backoff on 429/5xx, graceful exit on outage instead of breaking the workflow
- Depends on freehire.me, a personal best-effort hosted service with no formal SLA
- Faceted filtering (skills/category/seniority dictionaries) is tech-first; not suited to non-technical roles yet
- Facets can be incomplete: postings with unresolved region/country are silently dropped by --region filters
- Self-hosting a full, continuously fresh mirror (millions of postings) is resource-heavy, so most users still rely on the hosted API
- Search + detail only — it deliberately does not touch the key-gated apply/save tracking features
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| FreeHire Tech Job Search Skill this page | 63 · Recommended | ★ 47k | 17d ago | MIT |
| Jobbank Search Skill | 57 · Use with care | ★ 47k | 17d ago | MIT |
| Codex CLI Builder ✓ OpenAI · Official | 55 · Use with care | ★ 28k | 4mo ago | — |
| Stable Interface Design | 50 · Use with care | ★ 107k | 12d ago | MIT |
| Node Modules Inspector — Dependency Audit Skill | 67 · Recommended | ★ 3k | 1mo ago | MIT |
Sibling skills in the repo: unlike linkedin-search, this skill queries a structured JSON API rather than scraping HTML, returning skills/seniority/category facets, and takes geography as structured facets (--region/--country) instead of a free-text --location flag. Unlike the four Danish portal skills (Jobindex, Jobnet, etc.), it is country-agnostic and works for any market out of the box; the Danish skills primarily demonstrate the pattern.
How did FollowSkills review this skill?
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.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →