hq-cowork-share

name: hq-cowork-share description: Share HQ vault paths from Cowork through links or direct grants. allowed-tools: mcphqhq_share

/hq-cowork-share — Share an HQ vault path from a sandboxed agent

Mints share-session URLs and grants ACLs on HQ vault paths from inside Cowork (or any sandboxed Claude Code plugin host). Equivalent to the unprefixed /hq-share skill, but routed through the host-side MCP server because the sandboxed agent cannot run the hq CLI directly.

Args: $ARGUMENTS — required path + optional flags.

Arg	Meaning
`<path>` (positional)	Vault path or prefix to share (e.g. `companies/foo/knowledge/x.md`). Required.
`--with <principal>`	Email, group id, or `@all`. Omit to mint a share-session URL instead.
`--permission read\|write`	Permission level (only meaningful with `--with`).
`--expires 15m\|1h\|24h`	Token expiry for share-session URL (default 15m, max 24h).

When to use this instead of `/hq-share`

You're in Cowork or another sandboxed plugin host — the regular /hq-share skill shells out to hq files share on the host, which isn't reachable from the sandbox.
You want the MCP tool-call surface — observable in the host's tool log.

On a normal host-side Claude Code session, prefer the unprefixed /hq-share.

What you do

Step 1 — Parse args

Extract the positional <path> and any optional flags. Without a path, ask the user which vault prefix to share.

Step 2 — Call the tool

Call mcp__hq__hq_share with:

{
  "path": "<path>",
  "with": "<principal>",          // omit if not set
  "permission": "read|write",     // omit if not set
  "expires": "15m|1h|24h"         // omit to use default 15m
}

Step 3 — Surface output

The minting turn is the ONE surface where the unredacted share-session URL is permitted in chat. Print it as a clickable markdown link so the user can copy it.

Hard rule (carried over from core/policies/hq-share-session-urls-are-capabilities.md): After this turn, NEVER paste the URL back into later turns, summaries, journals, handoffs, commits, PRs, Slack/email, or any persisted context. Refer to it as https://hq.{co}.com/share-session/<TOKEN_REDACTED> from then on. The token IS a capability — anyone who holds it can use the share.

If --with was used (direct grant, not URL), there's no token to print — just confirm the grant landed and surface any error from the tool.

Why this skill exists

hq files share runs on the host with the user's Cognito session and the local sync index — neither of which is visible from inside Cowork's Linux VM. The host-side MCP server in hq-pack-cowork runs the real hq files share, then returns its output back to the sandboxed agent. This skill is the in-session adapter.

name: hq-cowork-share description: Share HQ vault paths from Cowork through links or direct grants. allowed-tools: mcp__hq__hq_share