Skip to main content
Hibi ships a 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. 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.
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.

​
Install

The Hibi repository doubles as a plugin marketplace, so installing the skill is two commands.
1

Add the marketplace

2

Install the plugin

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.
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.
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 for how redundant selectors fuse into a confidence score.
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.
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.
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.
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.
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.

​
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.
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.

​
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.

CI, git hooks & agents

Wire Hibi into the SessionStart and Stop agent hooks, plus the GitHub Action and pre-commit hooks that share the same exit codes.

Quickstart

Install Hibi and record your first claim by hand to see what the skill automates.

Plugin source

SKILL.md, the CLI reference it loads on demand, and a drop-in CI workflow asset.