Workspace and skills
The workspace is the folder the agent reads on every conversation: your instructions, your profile, your private skills, and the places it is allowed to put files. A fresh install scaffolds ~/workspace; this page explains what is in it and how to repair or align it later.
Initialize
xiaohe workspace init
It is safe to re-run: existing files are never overwritten. It writes the workspace path to the local settings, creates the skeleton, copies the instruction template, and installs the harness aliases.
What it creates:
| Path | Purpose |
|---|---|
AGENTS.md | The instructions every agent reads (Codex, Claude, Hermes) |
PERSONAL.md | Your profile: name, how to address you, contact, preferences |
CLAUDE.md, .hermes.md | Aliases pointing at AGENTS.md |
.claude → .agents | Directory alias; .agents/skills/ is for private skills |
assistant/ | logs/, checkpoints/, knowledge/, pending/, prompts/ |
local/, share/, scripts/ | Project links, deliverables, and helper scripts |
tmp/ | Scratch space for downloads, screenshots, and exports |
On Windows, creating symlinks needs one administrator prompt. If you decline it, the aliases fall back to copies; run xiaohe workspace link later to convert them.
Fill in PERSONAL.md
AGENTS.md imports PERSONAL.md, but init only copies the example. Open ~/workspace/PERSONAL.md and replace the placeholders:
- your name and how you want to be addressed;
- role, affiliation, contact;
- communication and coding preferences;
- where deliverables should go;
- optional fixed knowledge-base entry points.
Until you do, xiaohe doctor reports that the file still uses template placeholders. That is a warning, not a broken install.
Skills
Skills are not copied into the workspace. There are two layers:
| Layer | Where it lives | How to list |
|---|---|---|
| Community | Ships inside the runtime | xiaohe skills list --tier community |
| Catalog (Pro) | Served by the Hub on demand | xiaohe skills list --tier catalog |
| Workspace | <workspace>/.agents/skills/ | xiaohe skills list --tier workspace |
.agents/skills/ being empty is normal: it is only for private or project-specific skills. Asking the agent “what skills do you have” also works — it lists the same catalog.
Catalog skill references/ files are not on disk; the agent fetches them through the Hub. Do not copy ~/.xiaohe/hub-cache into the workspace.
Health check
xiaohe doctor
It checks the workspace path, instruction aliases, PERSONAL.md (missing or still placeholder), and the required folders. Missing pieces usually mean a half-finished init; re-running xiaohe workspace init fixes them.
Staying aligned after upgrades
The workspace and the product template are independent. An upgrade does not rewrite your AGENTS.md.
xiaohe workspace diff # read-only comparison
xiaohe workspace baseline # record the reviewed anchor
Review the diff and merge only the parts that apply to you; do not replace the file wholesale. The workspace-align skill walks through that semantic review.
xiaohe workspace diff reports one of aligned, product-forward, local-change, both-changed, personalized, or no-baseline. The first fresh init records a baseline automatically.
Troubleshooting
| Symptom | What to do |
|---|---|
PERSONAL.md is missing | Re-run xiaohe workspace init |
doctor says PERSONAL.md still has template placeholders | Fill it in; init cannot write your profile |
local/, share/, or scripts/ missing | Re-run xiaohe workspace init |
.agents/skills/ is empty | Normal; skills come from the runtime and the Hub |
workspace diff says no-baseline | Review the diff, then run xiaohe workspace baseline |
Your AGENTS.md was not updated | Expected; use workspace diff and semantic review |
| Windows aliases are copies, not links | Run xiaohe workspace link and approve the UAC prompt |