Commands vs Skills vs Workers

4 min read Updated Oct 2026

Anyone who has heard all three words and isn't sure which one they're supposed to use.

The execution stack

Commands
what you type/plan/deploy/search/handoff+ 40 more

Workers
who you hirePersistent AI specialists: hire once with /newworker, run with /run

Skills
the playbooksinstruction files underneathHQ maintains these

You live on the top row · create workers when a job repeats

This is the single most common point of confusion for new HQ users, and the untangling is short:

A command is what you type, like the slash command /prd or /handoff.
A skill is the instruction file that implements a command (or a worker capability) behind the scenes.
A worker is a persistent AI specialist: a named team member with its own skills, context, and rules, which you create once and run whenever needed.

The execution pyramid#

shell

  YOU TYPE:        /prd            /run designer homepage-refresh
                     │                         │
  IMPLEMENTED BY:  the "plan" skill          the worker's "homepage-refresh" skill
                     │                         │
  OPTIONALLY RUN BY:                     the "designer" WORKER
                                     (persistent specialist with its own
                                      knowledge, voice, and guardrails)

As a day-to-day user: you use commands constantly, you create workers occasionally, and you touch skill files rarely, usually only when building something custom.

Concrete example#

You type the command /checkpoint. HQ reads the skill file at .claude/skills/checkpoint/SKILL.md and follows it. That file is the implementation. You never need to open it.
You type /newworker and create a worker called brand-writer for your company, with skills like weekly-newsletter. From then on, /run brand-writer weekly-newsletter runs that specialist with its own persona and context. It is the same specialist every time, and it gets better as its knowledge grows.
/run with no arguments lists every worker you have.

"I want to...": the decision table#

I want to...	Use this
Do a one-off task (plan, search, sync, share)	The matching command, like `/prd`, `/search`, `/hq-sync`, `/hq-share`
Repeat a task the same way every time (weekly report, brand-voice posts)	Create a worker with `/newworker`, then `/run {worker} {skill}`
See what specialists already exist	`/run` (no arguments)
Teach HQ a rule it should always follow	`/learn`. That becomes a policy, not a skill
Package a reusable procedure my team can invoke	Author a skill in your company's skills folder (below)
Change how a built-in command behaves	Usually you don't. Capture preferences with `/learn` instead

Where each lives on disk#

Thing	Location
Built-in commands/skills	`.claude/skills/{name}/SKILL.md` (shipped with HQ; replaced on upgrade)
Your personal skills	`personal/skills/{name}/SKILL.md`, which appears as `/{name}`, visible only to you
Company skills	`companies/{company}/skills/{name}/SKILL.md`, which appears with the company prefix, e.g. `acme:report`
Workers	`companies/{company}/workers/{worker-id}/` (company-scoped) or `core/workers/public/` (shipped); master list in `core/workers/registry.yaml`

This trips up almost everyone once, so here is the exact mechanics:

Where it saved. A skill is a folder containing a SKILL.md file. If you made it for yourself, it's at personal/skills/{name}/SKILL.md. If you made it for a company, the source of truth is companies/{company}/skills/{name}/SKILL.md. HQ also mirrors it into .claude/skills/{company}:{name}/ so the assistant can invoke it. If you see the same skill in two places, that's the mirror, not a duplicate you need to clean up. Always edit the copy under companies/{company}/skills/.
Why your teammate can't see it yet. Skills don't travel on their own. A company skill reaches teammates through sync: if the company is cloud-backed, run /hq-sync. The skill uploads with the rest of the company folder, and teammates receive it the next time they sync. A personal skill never syncs to anyone; that's the point of personal.
Sharing with someone outside the sync loop. For a one-off, /hq-share companies/{company}/skills/{name} creates a secure single-use link. But for teammates, company scope + /hq-sync is the right path. It keeps everyone permanently up to date.

So the recipe for a shared team skill: create it under companies/{company}/skills/, run /hq-sync, and tell your teammates to sync.

Common questions#

Is a command the same thing as a skill?

Nearly. Every command is backed by a skill file, and most skills surface as a command. The distinction matters only when you're authoring: you write skill files; you type commands.

When is a worker worth creating instead of just asking in chat?

When you'll do the task more than a few times and consistency matters (same voice, same checks, same output format). A worker also accumulates its own learnings, so run five becomes better than run one.

Can a worker use my company's knowledge?

Yes. That's the main advantage. A company-scoped worker loads its company's knowledge and policies, and never another company's.

Do skills run automatically?

No. Skills run when you invoke a command, run a worker, or the assistant explicitly chooses one for your request. Standing "always do X" rules are policies, made with /learn. See Teaching HQ.

If you get stuck#

If a skill you created doesn't show up as a command, start a fresh session. Skills are discovered at session start. If a teammate can't see a shared skill, confirm the company is cloud-backed and both of you have run /hq-sync (see the sync guide). Still stuck? /hq-bug.