How to use the freehire Tech Job Search agent skill

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file and supporting files that an AI agent loads when a request matches the skill's description. This skill tells the agent how to query the freehire.me job aggregator through its public API and read back structured results.

Once installed, you can ask by keyword, region, country, seniority, skill, work mode or how recently a job was posted. Each result includes the full job description, so the agent does not need to open each posting separately. The skill can also look up one posting by its freehire slug, including a posting that has since closed.

• Keyword search over title, skill and role, with OR alternatives and title-only matching
• Facet filters for region, country, city, seniority, category, skill, company and remote mode
• Posted-within-N-days filtering through --jobage
• Lookup of one posting by slug with detail

Install the freehire-search skill

Option one: download the ZIP for this skill from this page and unzip it into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to limit it to that project.

Option two: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

The skill's CLI runs with Bun, so you also need the Bun runtime installed. The CLI has zero runtime dependencies, so no package install is required to run it.

• Download the ZIP from this page
• Unzip into ~/.claude/skills/ (all projects) or .claude/skills/ inside a project
• Or upload the ZIP under Settings → Capabilities → Skills in the Claude apps
• Make sure the Bun runtime is installed

Ask for jobs with natural requests

You do not need to type the CLI command yourself. The skill triggers on requests about tech roles, such as finding a tech job, software job search, developer jobs, engineering vacancies, data or ML jobs, DevOps roles, remote developer jobs, or asking whether there are any jobs for a given tech role in a given place.

The skill is scoped to technical roles. Requests for non-technical jobs are outside its tuned filtering and coverage.

• "Are there any Go backend jobs in Germany?"
• "Find remote senior DevOps roles posted in the last 7 days."
• "Look up this freehire job posting: <slug>"

Filter a search by region, country, seniority and skills

Location is a facet, not free text. Use --region for macro-regions such as eu, uk or north_america, and --country for ISO alpha-2 country codes such as DE or GB. Use --region eu,uk to cover Europe as a whole, since eu alone does not include the UK. The base search command is shown below; the agent builds the flags from your request.

Use -q for keywords. Two operators are supported: OR between alternatives, written in uppercase, and a leading title: to match only the job title. Plain space-separated words are not treated as a union, so use OR for alternatives.

• --seniority: junior, middle, senior, staff, principal, lead
• --category: for example backend, frontend, fullstack, devops, ml_ai, qa
• --skill: canonical skill names, comma-separated
• --remote: remote, hybrid or onsite
• --jobage: posted within N days
• --limit defaults to 25 results per page

Keep searches cheap and read descriptions only when needed

Full descriptions are verbose. Keep --limit modest and filter by title and company before reading bodies. For a quick scan, add --no-description, which keeps every other field and drops the bodies. Fetch the body of a shortlisted job with detail, or rerun the search without the flag.

Use detail only to look up one posting by slug, for example one from your tracker or a posting that is closed and no longer appears in search. Do not loop detail over search results, because search already returns full descriptions.

• Use --no-description for a discovery pass
• Use --description-format markdown (default), text or html when you need a specific rendering
• Use --format json (default), table or plain for output

Safety notes: scripts, network and what the skill does not do

This skill runs scripts and uses the network. It sends requests to freehire.me, or to the URL set in FREEHIRE_API_URL if you point it at a self-hosted instance. Reads are public and need no login, no API key and no account.

The skill only reads public listings. It does not apply to jobs, does not automate applications and does not access private accounts. Its tool permission is limited to running the skill's cli/src/cli.ts with bun.

• Network access is needed to freehire.me or your FREEHIRE_API_URL
• No authentication or API key is used
• The skill's allowed tool is bun run on its cli/src/cli.ts
• Automatic job applications and private account access are out of scope

Point the skill at a self-hosted freehire API

The freehire backend is a separate MIT-licensed project that runs with Docker Compose via make up, serving the API on port 8080. Set FREEHIRE_API_URL to use it. Be aware that a full, continuously fresh mirror of the corpus is resource-heavy, so most self-hosters either crawl a subset of sources or point the variable back at the hosted API.