xiv (skill)

The home/router skill: maps user intent to the right reference doc and command family.

This is the front door for any agent driving the CLI. It triggers whenever someone invokes /xiv, says "use xiv to …", asks to implement or ship a Linear issue, review or drive a PR, build a stacked feature, or check on a running workflow — even without naming a subcommand. Its job is not to know everything; it is to figure out the intent, open exactly one matching reference doc, and follow it.

Structure

SKILL.md holds the routing table, the operator mindset, and the standing guardrails. Six reference docs carry the per-task depth, loaded one at a time:

Routing is by intent, not surface words: a request that mentions "stack" but really asks "is it stuck?" routes to smithers-ops.md, whose cross-links lead back to the stack doc if needed. Most tasks need exactly one doc.

The operator mindset

The skill frames every workflow as a loop, not a command that returns:

1. Launch the right command for the task.
2. Watch it — xiv ps, xiv logs, xiv ui, xiv stack triage. A quiet run is usually working; judge by progress, not silence.
3. Babysit — resume transient failures, but stop and escalate anything unclassifiable (auth expiry, rebase conflicts, repeated test failures).
4. Report what happened, especially anything escalated.

Standing guardrails

These hold across every xiv flow unless the human explicitly overrides them:

• xiv panic (alias for xiv down) is the kill switch for a runaway or credit-burning run — reach for it first, diagnose after.
• Never merge a PR. Merging is always the human's call.
• Never submit or push a review without explicit instruction — generating one is fine; posting it is a separate, human-authorized step.
• Never push someone else's branch or force-push unasked.
• Keep the tooling anonymous. Nothing that lands in a repo or on GitHub — commits, PR bodies, review comments, branch names — may name xiv or Smithers.
• Default to the cheap model tier and the default iteration cap. Raise XIV_TIER or --max-iterations only when the human asks or the task is genuinely hard, and say so. A loop burning passes is a signal to escalate, not to buy more passes.
• Don't hardcode flags from memory. xiv <command> -h and xiv how-to are the source of truth.

Picking within the xiv pr family

The most common routing mistake is "review"-shaped requests, so the skill spells out the axis that matters: does code get changed and pushed?

• xiv pr review — inbound: review and (optionally) submit comments; never pushes code.
• xiv pr fix — outbound, one-shot: apply the findings already on a PR, push once.
• xiv pr refine — outbound, short loop: settle CI status and human comments, push.
• the xiv-review-core skill — the judgment alone: print findings, post nothing, run nothing.

A "don't push / don't submit" constraint rules out fix and refine. When intent is genuinely unclear, the skill says to ask rather than guess, because two of the four mutate and push code.

Tool allowlisting

The skill's frontmatter restricts the agent to Bash(xiv:*), Bash(smithers:*), Bash(gh:*), Bash(git:*), and Bash(jj:*) — enough to launch, observe, and inspect, and nothing that edits files. The much tighter allowlist for unattended supervision lives in xiv-operator.

Relation to the CLI

The skill duplicates no flag documentation on purpose — it routes to -h output and xiv how-to so it can't drift from the CLI. It also routes to the other xiv skills at the right moments: stack-plan before a stacked build, xiv-operator during one, and xiv-review-core for any review judgment. For how the site as a whole is meant to be read by agents, see For Agents.