> ## Documentation Index
> Fetch the complete documentation index at: https://npupko.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hibi Agent Skill for Claude Code: Setup and Usage Guide

> Install the Hibi Agent Skill for Claude Code to teach your agent the full Hibi loop: recording claims, reading verdicts, and acting on remediation menus.

Hibi ships a [Claude Code](https://claude.com/claude-code) **Agent Skill**: a
bundle of instructions a coding agent loads on demand to learn how to use a tool
the right way. The Hibi skill teaches the agent the whole loop: set up the store
in a fresh repo, record well-anchored claims, run the everyday `check` / `diff` /
`query` / `status` / `list` commands, read the two-axis verdict, act on the
remediation menu each flag carries, and manage the document lifecycle.

The skill is the agent-facing half of the same idea the rest of these docs
describe for humans. Hibi is **deterministic** (no model runs in the check loop),
so the skill never asks the agent to judge whether a doc is stale. It teaches the
agent to ask Hibi, and to act on the answer.

## Mental model: the deterministic half of the loop

A coding agent edits code all day. Left alone, it reads a doc or an `AGENTS.md`
file, trusts it, and edits against it, even when that doc has fallen out
of sync. Hibi is the deterministic check that closes that gap. The skill wires the
agent into two moments of its own session.

```mermaid theme={null}
sequenceDiagram
  participant A as Coding agent
  participant H as hibi
  A->>H: before trusting a doc: status --doc CLAUDE.md
  H-->>A: current? (exit 0) or STALE (exit 2/3)
  Note over A,H: agent trusts only a current doc
  A->>A: edits code
  A->>H: after editing: diff --since base
  H-->>A: verdict + remediation menu per flagged claim
  A->>A: read recommended / actions[].command, then act
```

Hibi flags **and tells the agent what to do about it**. Every drift verdict
carries a `remediation` menu: a `recommended` action id (or `null` when intent is
ambiguous) and an ordered `actions` list. A `deterministic` action arrives with a
ready-to-run `command` — claim id already filled in, like
`hibi reanchor asrt_…` — so the agent runs it directly instead of re-deriving the
next step. A `prose` action means the agent (or a human) rewrites the doc or code;
the engine never writes prose itself. A flag is always a request to **re-verify**,
not a claim that the doc is wrong.

<Note>
  The skill guides the agent; it does not bundle the `hibi` binary. The agent
  installs Hibi the usual way (a prebuilt binary or `bun add @npupko/hibi`) while
  it follows the skill.
</Note>

## Install

The Hibi repository doubles as a [plugin
marketplace](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces), so
installing the skill is two commands.

<Steps>
  <Step title="Add the marketplace">
    ```
    /plugin marketplace add npupko/hibi
    ```
  </Step>

  <Step title="Install the plugin">
    ```
    /plugin install hibi-cli@hibi
    ```
  </Step>
</Steps>

Run `/plugin marketplace update` after the repository changes to pull the latest
version.

## What the skill teaches

Claude loads the skill when you ask it to work with Hibi, and even when you don't
name the tool but describe the problem it solves: docs drifting from code, a stale
`README` or `AGENTS.md`, "keep the docs honest when the code changes". You can also
invoke it on demand as `/hibi-cli:hibi`.

<AccordionGroup>
  <Accordion title="Bootstrapping a repository" icon="seedling">
    Install Hibi, run `hibi init` to create the `.claims/` store (a committed
    directory beside your docs, one file per claim, with a per-repo banner nonce),
    commit the store, and seed the first claims. The agent learns that `.claims/`
    is tracked in git, not ignored: the anchors are the baseline that makes
    `check` work offline.
  </Accordion>

  <Accordion title="Recording claims well: span-first" icon="anchor">
    The skill's core lesson is precise anchoring. You point Hibi at the
    documented sentence (`--doc-quote`) and the exact code span that backs it
    (`--code-file` + `--code-quote`), so a real change trips the claim while a pure
    reformat does not. `hibi coverage --doc <p>` reports which blocks of an
    existing document are backed by a claim vs uncovered, so the agent grounds the
    uncovered prose or prunes it. See [Anchors & selectors](/anchors) for how redundant selectors fuse
    into a confidence score.
  </Accordion>

  <Accordion title="The everyday loops" icon="arrows-rotate">
    Six read-only commands, each tied to a moment:

    * `hibi query --path <p>`: **before** editing a file, ask which claims cover it.
    * `hibi diff --since <ref>`: **after** editing, ask which claims the change invalidated.
    * `hibi check`: verify every claim as a gate (in CI or a hook).
    * `hibi status --doc <p>`: a read-time check before the agent trusts a single doc.
    * `hibi list --state gating`: triage the whole suspect set, one lean row per claim, most-severe-first — swap in `--state orphaned` for un-relocatable claims or `--state suggested` for advisory ones.
    * `hibi doctor`: a store-health sweep (orphaned anchors, stranded and duplicate claims); informational, always exits `0`.

    These read-only verbs (`check`, `diff`, `status`, `query`, `list`, `doctor`)
    are **pre-approved in the skill's `allowed-tools`**, so the agent can run them
    without a per-call permission prompt. The mutating verbs (`record`, `reanchor`,
    `retire`, `relocate`, …) are not, so a change to the store always passes through
    you.
  </Accordion>

  <Accordion title="Reading the verdict and its remediation menu" icon="scale-balanced">
    The skill teaches the agent to read a verdict like
    `doc:unchanged · code:changed · behavior:at-risk` — anchor resolution per side
    (`doc:…` / `code:…`), plus the behavioral axis on behavioral claims — and which
    results gate (`changed`, `orphaned`, `ambiguous`, `expired`, `refuted` on an
    enforced claim → exit `2`) versus warn (`moved`, `at-risk` → exit `3`). But the
    agent rarely has to map verdict→action itself: each flag carries a
    `remediation` menu with a `recommended` action and an ordered `actions` list.
    The agent reads `recommended` (or the safest applicable action when it is
    `null`) and acts on it. Full detail in [Verdicts, states & exit codes](/verdicts).
  </Accordion>

  <Accordion title="Acting on a flag: follow the menu, don't silence it" icon="rotate">
    When a claim is flagged, the agent reads the verdict's `remediation` block
    rather than re-deriving a fix. A `deterministic` action carries a ready-to-run
    `command` with the claim id pre-filled — `hibi reanchor asrt_…` for a clean
    relocation, `hibi retire asrt_…` for a genuinely obsolete claim — which the
    agent runs directly. A `prose` action has no command: the agent rewrites the
    doc or code, then re-runs `check`. To withdraw a claim the agent calls
    `hibi retire <claim-id>` (which keeps the audit trail), **never** deletes the
    record file to make the check pass. The skill is explicit that a flag means the
    evidence moved (suspect, not false) and that a human decides what the prose
    should now say.
  </Accordion>

  <Accordion title="Managing the document lifecycle" icon="arrows-spin">
    When a newer document replaces an older one, the agent records the relationship
    with `hibi supersede --new <p> --old <p> --type supersedes|amends`, marks an
    author-withdrawn document with `hibi retract --doc <p>`, and moves an obsolete
    document out of the read path with `hibi archive`. (To withdraw a single
    *claim* rather than a whole document, it uses `hibi retire <claim-id>`.) See
    [Trust, enforcement & lifecycle](/lifecycle).
  </Accordion>
</AccordionGroup>

<Warning>
  The skill never teaches the agent to decide staleness itself. That judgment is
  Hibi's deterministic job. The agent's role is to run the checks, read the
  verdict and its remediation menu, and either run the deterministic command or
  draft the prose fix a human merges.
</Warning>

## Wiring it into the session lifecycle

Beyond the skill's instructions, you can bind the two moments above to Claude
Code's session hooks so they fire automatically:

* **SessionStart** → `hibi status --doc CLAUDE.md` (or whichever instruction file
  the agent is about to rely on): the read-time gate, so the agent only trusts a
  doc that comes back clean.
* **Stop** → `hibi diff --since origin/main`: re-verify only the claims the
  session's edits could have touched, so a drift the agent introduced surfaces
  before it leaves the loop.

<Note>
  This is a **pattern, not a packaged install.** Hibi ships no hook config of its
  own; you register these commands in your own Claude Code settings (or your
  team's shared config). Both are read-only `status` / `diff` calls, so they gate
  and report without ever touching the store.
</Note>

## Where this fits

The skill is one consumer of Hibi among several. The same exit codes and verdicts
drive a CI gate and git hooks, covered alongside the agent loop on the CI page.

<CardGroup cols={2}>
  <Card title="CI, git hooks & agents" icon="robot" href="/ci">
    Wire Hibi into the SessionStart and Stop agent hooks, plus the GitHub Action
    and pre-commit hooks that share the same exit codes.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install Hibi and record your first claim by hand to see what the skill
    automates.
  </Card>
</CardGroup>

<Card title="Plugin source" icon="github" href="https://github.com/npupko/hibi/tree/main/plugins/hibi-cli">
  `SKILL.md`, the CLI reference it loads on demand, and a drop-in CI workflow asset.
</Card>