Lesson 7 of 7 · HQ fundamentals

Create, Train, and Share a Reusable HQ Worker

Build a worker for one job, see the files that make it up, teach it your look, and share it with your team.

Begin lesson

Written path: 9 steps

Before You Begin

HQ is installed and you can start a session for your company.
You’re allowed to create workers for the company.
A public website whose look you’d like the worker’s pages to follow.
To share it: your company is set up for your team (see Lesson 2) and your teammate is a member.

Step 1: Pick one job
A worker does one repeatable job well instead of trying to do everything. This lesson builds a landing-page generator. It has a role, skills, knowledge, and examples, and it gets better as you add to them.
Expected
You know what job your worker does and how it’s different from a single skill.
COMPANY WORKERlanding-page-generator
A page brief goes in. A deployable landing page comes out.
ROLELanding pagesone repeatable job
SKILLSgenerate-landing-pagehow it does the job
KNOWLEDGEAesthetic packwhat the team knows
EXAMPLESPast pageswhat good looks like
A SINGLE SKILL
One set of instructions that stays as written. A worker keeps all four layers, and they get better every time the team adds to them.
Step 2: Create the worker
Start a session for your company, then run /newworker with a short name for the job.
CommandType exactly as shown
```
> /startwork awesomeco
> /newworker landing-page-generator
```
Expected
HQ starts building the worker and asks a few questions.
Note
awesomeco is an example. Use the company the worker belongs to.
hq — claude
✻ Welcome to Claude Code · cwd: ~/hq
>
Step 3: Answer HQ’s setup questions
Answer in your own words. In this example: keep it to AwesomeCo, have it build pages you can publish, and run it when you ask.
PromptSend in your AI session
```
› AwesomeCo only
› Deployable page (code)
› On-demand
```
Expected
HQ creates the Landing Page Generator for your company.
Note
AwesomeCo is an example. Pick your own company.
hq — claude
⏺A few quick questions before I scaffold it:
1/3 Where should this worker live?
› 1. AwesomeCo only
2. Shared across all my companies
3. Just me (personal)
>
Step 4: Look at the worker’s files
Open the worker’s folder and look at its settings file, readme, and landing-page skill.
Go toOpen this place
```
→ worker.yaml
→ README.md
→ skills/generate-landing-page.md
```
Expected
You can see what the worker does, how it runs, and which skill it uses.
Note
They’re in companies/[company]/workers/landing-page-generator/. Swap [company] for your company’s folder name.
companies/awesomeco/workers/landing-page-generator/
EXPLORER
▾landing-page-generator
·README.md
▾skills
·generate-landing-page.md
·worker.yaml
worker.yaml
1worker:
2 id: landing-page-generator
3 name: "Landing Page Generator"
4 type: CodeWorker
5 company: awesomeco
6execution:
7 mode: on-demand
8 max_runtime: 15m
9context:
10 base:
11 - companies/awesomeco/knowledge/README.md
12skills:
13 - id: generate-landing-page
14verification:
15 approval_required: true
Step 5: Teach it your look
Point HQ at a website you like and ask it to save the design style for this worker.
PromptSend in your AI session
```
› I want this worker to have more specific design instructions. Please reference hqforwork.com and build a design and aesthetic pack this worker can use.
```
Expected
HQ reads the site and asks how closely new pages should follow it.
Note
hqforwork.com is the example here. Choose a site you’re allowed to reference.
hq — claude
⏺Done. Your Landing Page Generator is built and registered for AwesomeCo.
>
Step 6: Choose how closely to match it
Once HQ has read the site, pick how closely the worker’s pages should match it.
ChoosePick this in HQ
```
— Select Match it closely
```
Expected
HQ saves the design style and builds it into the worker, so it’s used every time.
hq — claude
⏺How closely should AwesomeCo pages follow the hqforwork.com aesthetic?
1. Match it closely — pages look like they belong to the same family
2. Same system, AwesomeCo colors — keep the structure, swap in your brand
3. Capture it faithfully — save an accurate record, decide later
>
Step 7: Check that it stuck
Make sure the design pack is saved in your company’s knowledge, and that the worker’s settings and skill both point to it.
Go toOpen this place
```
→ companies/[company]/knowledge/design/hq-aesthetic-pack.md
→ worker.yaml
→ skills/generate-landing-page.md
```
Expected
Every time the worker runs, it starts from your saved design style.
companies/awesomeco/knowledge/design/hq-aesthetic-pack.md
HQ Aesthetic Pack
Pulled from hqforwork.com. Every AwesomeCo page the Landing Page Generator builds follows it.
#0d0d0f#141416#1aa64f#f2efe9Geist · tight trackingSquare buttons
worker.yaml
1context:
2 base:
3 - companies/awesomeco/knowledge/README.md
4 - companies/awesomeco/knowledge/design/
5 hq-aesthetic-pack.md
skills/generate-landing-page.md
1## Steps
21. Load hq-aesthetic-pack.md first
32. Plan the sections
4…
5Check: aesthetic_pack_conformance
Step 8: Share it and hand off
Ask HQ to share the worker with a teammate, send them a DM, and wrap up with a handoff.
PromptSend in your AI session
```
› Share this worker with [teammate], send an HQ DM, and hand off.
```
Expected
Your teammate can use the same worker and design style, and your session is saved.
Note
Swap [teammate] for your teammate’s name.
hq — claude
⏺Done. The worker now loads the aesthetic pack on every job.
>
Step 9: Run it and keep making it better
Run the worker whenever you need a new page. When your team finds a better way to do something, add it to the worker’s skills, design pack, or examples.
CommandType exactly as shown
```
> /run landing-page-generator generate-landing-page
```
Expected
Each run uses everything your team has taught it so far.
hq — claude
● Maya's MacBook
✻ Welcome to Claude Code · cwd: ~/hq
>

You’re done when

Your worker exists, it uses your saved design style every time, and your teammate can use it and improve it too.

Hit a snag? Here’s the fix.

My teammate can’t see the worker

Sharing only reaches teammates when your company is set up for your team. Check they’re a member, then have them run /hq-sync.

/run says it can’t find the worker

Start the session in the company that owns the worker with /startwork [company], then try again. Company workers only show up inside their own company.

The worker ignores the aesthetic pack

Ask HQ to check that worker.yaml and the skill both point at the pack file. If one of them doesn’t, ask HQ to add the reference.

Something else going on? The HQ knowledge base walks through the most common fixes, or reach out and we’ll help you get unstuck.