Skills
The agent skills xiv ships, what each is for, and how they are installed.
What a skill is here
A skill is a package of prose instructions — a SKILL.md, plus optional reference docs and
scripts — that an agent loads on demand when a task matches the skill's description. The workflow
pack is code the Smithers engine executes; skills are the other half: instructions read by
whatever agent is driving xiv. They carry the judgment and discipline that can't live in a
CLI flag — how to route a request, when to escalate a stuck run, what counts as a review finding
worth flagging.
Most skills follow the same structure:
SKILL.md— the core instructions, with adescriptionthat tells the agent when to trigger.references/*.md— deeper per-topic docs the agent loads only when needed.scripts/— occasional helper scripts (currently only xiv-operator).
How they are installed
xiv init (first-time) and xiv update install two separate things: the workflow pack into
SMITHERS_HOME, and this repo's skills into your agent directories. The skills half shells out to
the skills CLI:
npx --yes skills@latest add <repo-root> --skill '*' [--global]Design decisions baked into that call (from installSkills in src/manifest.ts):
- Every skill installs (
--skill '*') — the set is curated in this repo, so there is nothing to choose per-skill. - Which agents to target is your call — the command deliberately avoids
--all(which would silently install into every agent it can find) and leaves--agentunset so the CLI prompts. add, notupdate— skills always re-install from the current working tree, which may be ahead of any commit. Editing a skill and runningxiv updatehands your agent the new text.- A skills failure never fails a pack update — the skills step needs the network; if it fails,
the pack install still succeeds and the command warns. Rerun the skills half alone with the
npxcommand above, or skip it entirely with--no-skills.
See Managed files for the pack half of the install.
The seven skills
| Skill | One-liner |
|---|---|
| xiv | Home/router skill: maps user intent to the right reference doc and xiv command, and carries the operator guardrails. |
| xiv-operator | Babysits a long xiv stack build: polls triage, auto-resumes transient failures, escalates everything else. |
| xiv-review-core | The code-review judgment contract — also what the automated local review step follows. |
| stack-plan | Interactive stacked-feature planner: assigns issues to repos, confirms unclear ones, excludes non-code work. |
| review-path | Plans a human reading order for a diff — comprehension, not bug-finding. |
| test-writing | Adversarial test design: derive the contract from the spec before reading the implementation. |
| test-audit | Evidence-backed audit of an existing suite, judged on its power to falsify the implementation. |
The first four are xiv-specific — they wrap or complement the CLI and its workflows. The last three (review-path, test-writing, test-audit) are general-purpose engineering skills that happen to ship from this repo and hold anywhere an agent writes or reviews code.