hq-cowork - SKILL.md Agent Skill

name: hq-cowork description: Discover and dispatch HQ capabilities from a sandboxed Cowork plugin host. allowed-tools: mcphqhq_whoami, mcphqhq_sync, mcphqhq_team_sync, mcphqhq_search, mcphqhq_qmd, mcphqhq_secrets_exec, mcphqhq_secrets_list, mcphqhq_share, mcphqhq_files, mcphqhq_members, mcphqhq_groups, mcphqhq_dm, mcphqhq_packages, mcphqhq_modules, mcphqhq_meetings, mcphqhq_sources, mcphqhq_signals, mcphqhq_feedback, mcphqhq_run, mcphqhq_cli

/hq-cowork — Native HQ from a sandboxed agent

Cowork's bash runs in an isolated Linux VM that cannot see ~/.hq (Cognito auth) or reach the host's hq / qmd binaries. hq-pack-cowork ships a host-side stdio MCP server that runs those binaries with full auth and exposes them as mcp__hq__* tool calls. This skill is the map: it tells you which tool covers which HQ capability and how to call it.

Args: $ARGUMENTS — optional. A capability keyword (e.g. sync, secrets, meetings) jumps straight to that section's guidance. No arg = print the full capability map below and ask what the user wants.

Capability map

Need	Tool	Notes
Confirm identity / session	`mcp__hq__hq_whoami`	email + session expiry. First call to sanity-check wiring.
Bidirectional sync	`mcp__hq__hq_sync`	`company` to scope, `personal: true` for personal vault, else all.
Pull team content	`mcp__hq__hq_team_sync`	one-way down-sync; `team` to scope, `dryRun` to preview.
Search HQ content	`mcp__hq__hq_search`	qmd hybrid. See `/hq-cowork-search`.
qmd read/list/ask/index	`mcp__hq__hq_qmd`	Same qmd-first workflow as default HQ sessions: collections/status/list/get/multi_get/search/ask/update.
Run cmd with a secret	`mcp__hq__hq_secrets_exec`	values injected as env, NEVER returned. See `/hq-cowork-secrets`.
List secret names	`mcp__hq__hq_secrets_list`	names/metadata only — no values.
Share a vault path	`mcp__hq__hq_share`	mint URL or grant ACL. See `/hq-cowork-share`.
Read vault objects	`mcp__hq__hq_files`	browse / cat / acl / search / shared-with-me / get. See `/hq-cowork-files`.
Memberships	`mcp__hq__hq_members`	list / invite / revoke.
Permission groups	`mcp__hq__hq_groups`	list / members / create / delete / add / remove.
DM a teammate	`mcp__hq__hq_dm`	menubar notification. See `/hq-cowork-dm`.
HQ packages	`mcp__hq__hq_packages`	list / install / remove / update.
Knowledge modules	`mcp__hq__hq_modules`	list / add / sync / update.
Meetings	`mcp__hq__hq_meetings`	list / get / search / transcript / notes. See `/hq-cowork-meetings`.
Sources	`mcp__hq__hq_sources`	meeting/email/slack/linear/notion attached to an entity.
Signals	`mcp__hq__hq_signals`	action_item / commitment / decision / key_point / risk / summary.
File a bug / feature	`mcp__hq__hq_feedback`	`action: bug\|feature`, `title`, `body`.
Run with `.env.schema` secrets	`mcp__hq__hq_run`	validates cwd, injects env, returns child output only.
Long-tail HQ CLI	`mcp__hq__hq_cli`	guarded escape hatch for commands not yet wrapped. See `/hq-cowork-cli`.

Security envelope (carries over from HQ core policies)

Secret values never cross the MCP boundary. hq_secrets_exec injects them into a child process env; hq_secrets_list shows names only. There is no value-revealing tool. Never try to echo a secret to capture its value.
Cross-company isolation. Always pass company explicitly when crossing contexts. Never let the server fall back to another company's scope. If the scoped creds fail, stop and ask — don't retry against a different company.
Share-session URLs are single-use capabilities. hq_share returns the minted URL once. Print it that turn, then redact as https://hq.{co}.com/share-session/<TOKEN_REDACTED> everywhere after.
Escape hatch stays guarded. hq_cli blocks login/logout/onboard, secret-value output, raw hq secrets set|exec, and hq run (use hq_run instead).

When to use this instead of the unprefixed skills

Use the hq-cowork-* family (and direct mcp__hq__* calls) only inside Cowork or another sandboxed plugin host. On a normal host-side Claude Code session prefer the unprefixed /hq-sync, /hq-share, /search, /hq-secrets, /dm, etc. — fewer hops, same result.

What you do

If $ARGUMENTS names a capability, skip to that tool and call it with the user's parameters. If ambiguous or empty, show the capability map and ask.
Prefer the dedicated hq-cowork-* skill when one exists (search, share, secrets, files, dm, meetings) — it carries the per-capability nuance.
Always start a fresh wiring with mcp__hq__hq_whoami if a tool errors with an auth/ENOENT message — that confirms whether the host server is logged in and has hq/qmd on PATH.