All articles
On this page
How HQ Works
Capability Packs: Installing and Managing Them
Builders and champions who want to add capabilities to HQ, and anyone wondering why a command from the docs is missing on their machine.
HQ deliberately ships small. The core scaffold gives you the essentials, and everything richer arrives as a capability pack: a signed bundle you install once, which then shows up in your sessions like it was always there. This page covers what packs are, the two ways to install them, and the safety checks that run on every install.
What a pack is#
A pack is one downloadable bundle that can contain any mix of:
- Skills and commands, which appear as new slash commands in your sessions
- Workers, persistent AI specialists (see Commands, Skills, and Workers)
- Knowledge bases, reference material HQ can search and cite
- Policies, standing rules HQ follows
- Scripts, small helper programs the pack's skills call
- Hooks, scripts that run on session events (these get special safety treatment, covered below)
- MCP servers, connections to outside tools, which like hooks are never registered without an explicit confirmation prompt at install time
Official packs are published by the HQ team, and the catalog also carries curated packs from the open-source ecosystem, each credited to its creator. For where packs sit in the wider product family, see The HQ Ecosystem.
Where did the engineering pack go?#
The coding toolkit (commands like /tdd, /review, /execute-task, and /run-project) used to ship as a separate pack called hq-pack-engineering. It's now built into HQ again, so everyone has it and there's nothing to install. You may see a pack called hq-pack-core-skills in hq packs list. That's where HQ's built-in commands live. HQ installs and updates it for you, and it can't be uninstalled.
If you installed the old pack before, you can remove it so you don't have two copies:
hq packs uninstall hq-pack-engineeringInstalling without a terminal#
You don't need the command line. The HQ app has a pack manager called the Marketplace. To get there, click the Marketplace icon on the left rail. You can also click the Core button at the top-right of the HQ window and choose Marketplace. The Marketplace has three tabs:
- Browse (the one that opens first) shows approved packs you can install. Open a pack to install it, either just for you (Personal) or for a company you're an admin of.
- Installed shows the packs already in your HQ, with their versions and update or uninstall options.
- Submit is for publishing a pack of your own.
Installed packs show Update when a newer version is available. The Core menu also has Check for updates for HQ itself.
To see the individual skills and workers your packs have added, open a company and look in its Brain section (Skills and Workers). The Library item on the left rail is something else: it holds your personal files and what's been shared with you.
The Marketplace does the same thing as the terminal commands below, so it doesn't matter which you use.
For a walkthrough of installing and setting up one pack, see Getting Texts from Your AI with iMessage. For a pack that records your screen and writes a guide, see HQ Capture.
Installing from the terminal#
The hq CLI manages packs with four commands:
| Command | What it does |
|---|---|
hq install <pack> | Download, verify, and install a pack |
hq packs list | Show installed packs plus the curated catalog |
hq packs update [name] | Reinstall the latest version (add --check-only to just peek) |
hq packs uninstall <name> | Cleanly unwire and archive a pack |
Company scoping. From the terminal, a pack installs for your whole HQ. If the pack needs stored secrets (for example to connect an MCP server), add --company so HQ uses that company's secrets:
hq install <pack> --company <your-company>Packs always install into HQ's shared core/packages/ folder. Picking a company when you install only decides which company's secrets the pack can use.
Hooks and MCP servers. The install stops to ask before adding either. --allow-hooks and --allow-mcp skip those prompts, so only use them for packs you trust.
Do I need to sign in? Not to install. Marketplace packs download without an HQ sign-in. You'll still want to be signed in for anything that uses HQ Cloud, like company secrets or sync and sharing. hq login in the terminal and /hq-login inside a session sign in to the same HQ account.
What actually happens during an install#
Installation is one step from your side, with the sensitive parts still gated on you:
- The CLI downloads and verifies. The pack is fetched from the registry and its integrity is cryptographically verified (details in the safety box below).
- It wires into your HQ. The pack's content lands under
core/packages/{name}/and is linked into your sessions. Anything sensitive still needs your consent: the install pauses and asks before any hook or MCP server is added, and you can skip those parts.
Clean removal. Everything a pack adds is marked with the pack's prefix, so removal is complete: hq packs uninstall (or the Marketplace) finds every worker, command, skill, knowledge folder, policy, and hook the pack installed and unwires them. The pack folder is archived rather than deleted, unless you add --no-archive. If another installed pack depends on it, HQ stops and tells you which one.
The safety model, in plain English#
Packs are the one place where outside content gets to add behavior to your HQ, so the checks are strict:
- Every Marketplace download is cryptographically verified. The file's SHA-256 fingerprint must match the approved listing, and its digital signature must check out against HQ's platform key. A tampered pack is rejected before it's unpacked. Packs from a local folder without a signature only install if you add
--allow-unsigned. - Hooks require your explicit approval. Hooks are the most sensitive content because they run shell scripts on session events. Before any hook installs, HQ lists every hook the pack adds, warns that they run with your shell permissions, and waits for your yes.
- MCP servers require your approval too. HQ shows the full address of each server (or the local command it runs) before adding it, so you can spot anything unexpected.
- The capabilities field is a hint, not a guarantee. A pack's manifest can carry a
capabilitieslist naming the host surfaces it touches (hooks, scripts, network, filesystem, secrets). It's useful to read, but HQ doesn't enforce it. The hook and MCP prompts above are what actually protect you.
Agency kit#
If you run an agency with more than one client in HQ, the HQ Agency Kit is a starting point. Each client gets their own workspace with their profile, access and assets, and onboarding work, and your whole team delivers with the same set of skills.
- Setup is a six-question interview. An Agency Guide bot asks the questions and writes your agency playbook.
- Client onboarding runs through four approval gates: a sourced brief, an intake request, an audit, and a kickoff package. A strategist approves each one before anything reaches the client.
- A practice client, Northwind Labs, is included so you can try the whole flow before you add a real one.
To install it, open the Agency kit pack page and click Add to HQ.
Common questions#
Do I need to install packs on every machine?
Yes, a pack install is per-machine. The Marketplace or one hq install on each machine keeps it quick.
A pack update is available. Will updating break my changes?
Yes, if you edited the pack's own files. Updating replaces the whole pack folder with the latest version and doesn't check for your edits, so don't change files inside a pack's folder. Put your changes in your own skills or policies instead. To see whether an update exists without installing it, run hq packs update <name> --check-only.
Can my whole team get a pack automatically?
Company-scoped content travels to teammates through sync once it is in the company folder.
If you get stuck#
If a pack command is missing after an install, start a fresh session; commands are discovered at session start. If an install fails partway, run it again from the Marketplace or the terminal, and see The "I'm Stuck" Guide for the general decision tree. Still stuck? /hq-bug.