Content
81%Weight 40%Scale 1-5Reviews 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.
| Dimension | Reasoning | Score |
|---|---|---|
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 |