diff --git a/.agents/skills/freehire-search/SKILL.md b/.agents/skills/freehire-search/SKILL.md index c329216a..e6500867 100644 --- a/.agents/skills/freehire-search/SKILL.md +++ b/.agents/skills/freehire-search/SKILL.md @@ -81,6 +81,7 @@ bun run .agents/skills/freehire-search/cli/src/cli.ts search [-q ""] [ Key flags: - `--query ` / `-q ` — keyword search (title, skill, role). Full-text; optional. + Supports `OR` and `title:` (see "Query operators" below). - `--jobage ` — posted within N days (maps to `posted_within_days`). - `--page ` — 1-indexed page. Default 1. - `--limit ` / `-n ` — results per page (API limit). Default 25. @@ -89,6 +90,26 @@ Key flags: rendered. Default `markdown`, which keeps the posting's headings and requirement lists intact. `json` output only. +**Query operators.** `-q` understands two operators; the CLI passes the text through +unchanged and the API parses it: + +- `OR` between alternatives returns jobs matching **any** of them, e.g. + `-q "golang OR rust"`. Uppercase only: a lowercase `or` is an ordinary search + word. Plain space-separated words are **not** a union (`-q "golang rust"` returns + fewer jobs than `-q golang` alone), so use `OR` for synonyms and alternative stacks + instead of running one search per keyword. At most 5 alternatives; a 6th is + rejected with an error. An `OR` inside double quotes is literal text. +- A leading `title:` restricts that alternative to the job **title**, e.g. + `-q "title:staff engineer"` skips postings that merely mention the words in their + description. It applies per alternative, so repeat it on each one: + `-q "title:staff engineer OR title:principal engineer"`. It only counts at the start + of an alternative; `title:` in the middle is searched as text. Quotes work inside it: + `-q 'title:"staff engineer"'` matches the phrase. + +Facet flags, `--jobage`, `--page` and `--limit` apply to the combined result: every +alternative is filtered the same way, and a job matching several alternatives +appears once. + **Search results already carry the full description.** This skill queries freehire's agent search endpoint, which replaces the index's truncated preview with each posting's complete text, so a search of 20 roles is 1 request rather than 1 + 20. @@ -139,6 +160,12 @@ just returned only re-reads a description you already have. # Senior backend roles, table view bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table +# Go or Rust roles, one search (OR must be uppercase) +bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "golang OR rust" --remote remote --format table + +# Staff or principal titles only, not postings that mention them in passing +bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "title:staff engineer OR title:principal engineer" --format table + # Remote React roles in the EU bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "react" --remote remote --region eu --format table diff --git a/.agents/skills/freehire-search/cli/README.md b/.agents/skills/freehire-search/cli/README.md index 4901d6f5..e1d14e67 100644 --- a/.agents/skills/freehire-search/cli/README.md +++ b/.agents/skills/freehire-search/cli/README.md @@ -74,7 +74,7 @@ See `../SKILL.md` for the full flag reference and the hosted-dependency note. | Flag | Alias | Description | |------|-------|-------------| -| `--query` | `-q` | Keywords (title / skill / role). Full-text; optional. | +| `--query` | `-q` | Keywords (title / skill / role). Full-text; optional. `a OR b` matches either (uppercase `OR`, max 5 alternatives); a leading `title:` searches the job title only. | | `--jobage` | | Posted within N days (`posted_within_days`). | | `--page` | | 1-indexed page. Default 1. | | `--limit` | `-n` | Results per page (API limit). Default 25. | diff --git a/.agents/skills/freehire-search/cli/src/cli.ts b/.agents/skills/freehire-search/cli/src/cli.ts index 12dd1507..bd9773b8 100644 --- a/.agents/skills/freehire-search/cli/src/cli.ts +++ b/.agents/skills/freehire-search/cli/src/cli.ts @@ -79,6 +79,8 @@ USAGE SEARCH FLAGS --query, -q Keywords (title, skill, role). Full-text; optional. + "a OR b" matches either (uppercase OR, max 5); + a leading title: searches the job title only. --jobage Posted within N days (maps to posted_within_days). --page 1-indexed page. Default 1. --limit, -n Results per page (API limit). Default 25. diff --git a/.agents/skills/freehire-search/url-reference.md b/.agents/skills/freehire-search/url-reference.md index 8677ccf1..ebc50924 100644 --- a/.agents/skills/freehire-search/url-reference.md +++ b/.agents/skills/freehire-search/url-reference.md @@ -64,7 +64,7 @@ Query parameters used by the skill: | Param | Maps to CLI flag | Notes | |-------|------------------|-------| -| `q` | `--query` / `-q` | Keyword full-text query. | +| `q` | `--query` / `-q` | Keyword full-text query. Uppercase `OR` separates up to 5 alternatives (more is a 400); a leading `title:` restricts an alternative to the title. | | `limit` | `--limit` / `-n` | Page size. Default 25 in the CLI. | | `offset` | (derived) | `offset = (page - 1) * limit`. | | `posted_within_days` | `--jobage` | Restrict to postings from the last N days. | diff --git a/CHANGELOG.md b/CHANGELOG.md index c21161f0..17b313e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,15 @@ per-file diff commands. ## [Unreleased] +### Changed + +- **`freehire-search` documents the `OR` and `title:` query operators** (#674, + `.agents/skills/freehire-search/SKILL.md`, `url-reference.md`, `cli/README.md`, `--help`) - + freehire's search parses an uppercase `OR` between up to five alternatives and a leading `title:` + per alternative, but nothing told the agent, so "Go or Rust" became two searches merged by hand + or `-q "golang rust"`, which returns fewer jobs than `golang` alone. Measured live: `golang` + 3,550, `golang OR rust` 6,805. The CLI already passes `-q` through unchanged. + ### Fixed - **`freehire-search detail` no longer asks the API for a slug cut out of a URL on another