hq-cowork-search

name: hq-cowork-search description: Search HQ content from Cowork with full-text, semantic, or hybrid modes. allowed-tools: mcphqhq_search

/hq-cowork-search — Search HQ from a sandboxed agent

Searches indexed HQ content via the host-side qmd binary, surfaced as an MCP tool so a sandboxed agent (Cowork) can use it even though qmd isn't installed inside its Linux VM.

Args: $ARGUMENTS — query plus optional flags.

Arg	Meaning
`<query>` (positional, required)	Natural-language search query.
`-c <collection>` / `--collection <collection>`	Scope to one collection (e.g. `hq-infra`, `hq-knowledge`, `indigo`).
`-n <N>` / `--limit <N>`	Number of results (default 10, max 50).
`--format json\|md\|files`	Output format. Omit for the default human snippet.

Collections worth knowing about (varies per HQ install — run qmd ls on the host to enumerate):

hq-infra — skills, policies, hooks
hq-knowledge — core/knowledge/public/hq-core/
hq-workers
hq-projects
{company-slug} — per-company knowledge, one collection per company

When to use this instead of `/search`

You're in Cowork or another sandboxed plugin host — the regular /search skill (and the qmd charter rule that says "qmd first") relies on the qmd binary on PATH, which isn't true inside the sandbox.
You want JSON results for downstream programmatic use — pass --format json and parse the response.

On a host-side session, prefer the unprefixed /search or qmd query directly — fewer hops, same results.

What you do

Step 1 — Parse the query

Extract <query> (required) and optional flags. Without a query, ask what the user is looking for. If the query is vague ("find docs"), ask for a more specific phrase — qmd hybrid is good but not magic.

Step 2 — Call the tool

{
  "query": "<query>",
  "collection": "<collection>",   // omit to search all
  "limit": <N>,                   // omit to use default 10
  "format": "cli|json|md|files"   // omit to use default cli
}

Call mcp__hq__hq_search.

Step 3 — Surface results

For cli / md format, render the tool output as-is (already human-readable). For json / files, summarize: top 5 paths + scores, then offer to read the most relevant via the host MCP if the user wants the body.

If no results, suggest broadening — drop the collection filter, try a synonym, or fall back to qmd vsearch (pure semantic) via a follow-up call with a different query phrasing.

Why this skill exists

The HQ charter mandates "qmd first" for HQ search — but only a host-side session can actually shell out to the qmd binary. Inside Cowork's sandbox, neither qmd nor the index DB it reads (~/.qmd/) is reachable. The hq-pack-cowork MCP server runs qmd query (hybrid: expansion + RRF + rerank) on the host and returns the formatted result. This skill is the in-session adapter.

name: hq-cowork-search description: Search HQ content from Cowork with full-text, semantic, or hybrid modes. allowed-tools: mcp__hq__hq_search