CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

freehire-search

Use this skill to search live software / tech / data / engineering job listings across many countries and markets (and remote) via the freehire.me aggregator's public API, or to look up a specific posting. It aggregates roles from ~50 ATS platforms into one schema, so a single skill covers many markets — but its faceted filtering (skills, category, seniority) is tuned tech-first, so scope triggers to technical roles. Trigger phrases: find a tech job, software job search, developer jobs, engineering vacancies, data/ML jobs, DevOps roles, remote developer jobs, "are there any <tech role> jobs in <place>", look up this freehire job posting.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is exceptionally actionable — every command is executable, output shapes and error codes are documented, and the search-vs-detail workflow includes pre-flight facet validation and explicit error-recovery semantics. Its weaknesses are token efficiency (a self-hosting digression, backend implementation details, and duplicated notes) and a ~230-line monolithic file whose deep-dive sections could be split into one-level-deep references.

Suggestions

Trim the self-hosting section to the FREEHIRE_API_URL example plus one pointer line, cutting the backend stack detail (Go + PostgreSQL + Meilisearch, make up/Docker Compose) and the resource-heavy mirror caveat — none of it is needed to run a query; move the rest to a reference file if self-hosting must be documented.

State the full command once ("bun run .agents/skills/freehire-search/cli/src/cli.ts") and use a short alias like `cli` in the ten usage examples, saving the repeated ~60-character path per example.

De-duplicate the region guidance: "`us` is a country code, not a region" is explained both in the --region facet entry and again in the Output-formats diagnostics paragraph — keep it in one place and cross-reference.

DimensionReasoningScore

Conciseness

Mostly dense, non-obvious operational content, but there is real fat: the self-hosting digression ("The freehire backend is a separate MIT-licensed repo — strelov1/freehire (Go + PostgreSQL + Meilisearch) — that stands up with one command via Docker Compose" and the resource-heavy-mirror caveat paragraph), backend stack details Claude never needs to run queries, a duplicated note ("`us` is a country code, not a region" appears both in the facet list and again in the diagnostics section), and ten examples each repeating the full `bun run .agents/skills/freehire-search/cli/src/cli.ts` path. This fits anchor 3 ("mostly efficient but includes some unnecessary explanation or could be tightened"). Not 4: the self-hosting digression and repetitions are more than "minor instances"; not 2: there is no explanation of concepts Claude already knows and nearly every section carries operator-only knowledge.

3 / 5

Actionability

Every command is copy-paste ready: ten worked examples ("search -q 'golang OR rust' --remote remote --format table", "detail golang-zensar-2bxu6dxm --format plain") covering the common cases, exact flags with defaults and limits, the exact output schema ("{ \"meta\": { \"count\", \"page\", \"total\" }, \"results\": [...] }"), and exact error behavior (exit 1, stderr JSON, BAD_ARG/BAD_ID codes). Matches anchor 5 (fully executable, copy-paste ready, examples cover the common cases). Not 4: there are no gaps — even the cheap-discovery pass (--no-description) and its re-fetch path are specified.

5 / 5

Workflow Clarity

The workflow is unambiguous with explicit validation and recovery: pre-flight facet validation ("Discover the live values for a market at /api/v1/jobs/facets ... never invent facet values"), a clear search-vs-detail decision rule ("Do not loop detail over search hits ... reach for detail only to look one posting up by slug"), and full error-feedback semantics (unreachable API "exits non-zero with a clear message"; a 404 from an old self-hosted instance "is reported as an error naming the endpoint — never as an empty result set"; the REGION_VALUE_UNKNOWN warning is distinguished from errors; partial-data recovery via "widen or drop the facet" or "--region none"). Read-only skill, so the destructive/batch cap does not apply; the single action plus its error loops match anchor 5 under the simple-skill allowance. Not 4: validation checkpoints and recovery loops are explicit, not implicit.

5 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), so all guidance is inline in one ~230-line file — but with strong structure: clear section headers (Scope, Hosted-service dependency, When to use, Commands, Usage examples, Output formats, Partial data, Notes), a formats table, and clearly signaled external pointers (the CLI path and the /api/v1/jobs/facets endpoint). Fits anchor 4 (good structure, most content appropriately placed, minor organization gaps). Not 5: the file exceeds a lean overview — the self-hosting section and the deep query-operator/partial-data semantics are natural candidates for a one-level-deep reference file; not 3: nothing is buried and the inline material is operational rather than reference bulk in the anchor-3 sense.

4 / 5

Total

17

/

20

Passed

Description

91%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description explicitly states what the skill does (multi-market tech job search and per-posting lookup via freehire's public API) and when to use it, backed by a comprehensive, natural trigger-phrase list that even includes a question template. It is highly specific and clearly niched to this one aggregator, with only minor overlap risk against other job-board skills.

DimensionReasoningScore

Specificity

Quotes: "search live software / tech / data / engineering job listings across many countries and markets (and remote) via the freehire.me aggregator's public API", "look up a specific posting", "faceted filtering (skills, category, seniority)". These are several concrete, well-scoped actions with the data source named, matching anchor 4 ("Lists several specific actions; minor gaps in coverage"). Not 5: it stops short of a comprehensive action list (e.g., recency/company filtering and output handling appear only in the body); not 3: coverage goes beyond the bare 1–2 actions of the anchor-3 example. No first/second-person voice penalty — "Use this skill" is imperative, matching the rubric's own good examples.

4 / 5

Completeness

What: "search live ... job listings ... via the freehire.me aggregator's public API, or to look up a specific posting". When: "scope triggers to technical roles" plus an explicit "Trigger phrases:" list. Both what and when are answered explicitly with concrete trigger phrases — matches the anchor-5 example pattern exactly. Not 4: the 'when' is not merely present but enumerated; not below because neither half is vague.

5 / 5

Trigger Term Quality

Quotes: "Trigger phrases: find a tech job, software job search, developer jobs, engineering vacancies, data/ML jobs, DevOps roles, remote developer jobs, \"are there any <tech role> jobs in <place>\", look up this freehire job posting". This is a comprehensive set of natural phrases a user would actually say, with synonyms across role families plus a question template and a source-specific lookup phrase — matches anchor 5 (comprehensive natural terms including synonyms). Not 4: nothing common is missing; the phrase list even covers the natural-language question form.

5 / 5

Distinctiveness Conflict Risk

Quotes: "via the freehire.me aggregator's public API", "scope triggers to technical roles", "look up this freehire job posting". A clear niche (one named aggregator, tech-only scoping, source-specific lookup trigger) with minimal conflict risk — anchor 4. Not 5: generic triggers like "software job search" and "developer jobs" would also fire for sibling job-board skills (the body itself names a linkedin-search pattern), so overlap with closely related skills is more than minimal.

4 / 5

Total

18

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

MadsLorentzen/ai-job-search

Path

.agents/skills/freehire-search/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.