Ben Thomasson

4 minute read

I published the beliefs CLI tool on a Friday evening and went to bed. When I checked the repositories the next morning, four agents had independently adopted it. A fifth had been guided through its first use. Nobody told the other four to use it. They found the skill, read the documentation, and started tracking their beliefs.

But here’s the interesting part: what each agent did with it was completely different. And one agent looked at it carefully and said no.

The Adoption Timeline

Within six hours:

  • Researcher — 12 claims, all positive, sourced from CLAUDE.md
  • Reviewer — 12 claims, 2 warnings, sourced from specific entries
  • Verifier — 25 claims, 7 warnings, 3 retracted, sourced from specific entries
  • PI — 19 claims spanning 7 repos, full IN/OUT/STALE lifecycle
  • Quantum-lattice (guided) — 17 claims, 2 warnings, sourced from specific entries

Each agent also independently wrote its own usage guide. Six agents, six different guides, none of them copied from each other. They each explained the tool in terms of their own role.

The Verifier Won

Side by side, the verifier’s registry was objectively the most valuable:

Researcher’s registry:

  • 12 claims, 0 warnings, 0 retractions
  • All sourced from CLAUDE.md (a summary document)
  • No problem tracking whatsoever
  • Known open problems — missing derivations, falsified predictions, circular tests — completely absent

Verifier’s registry:

  • 25 claims, 7 active warnings, 3 retracted with reasons
  • Sourced from specific dated entries (primary evidence)
  • Full belief lifecycle: claims registered, flagged stale, retracted when superseded
  • Four warnings representing genuine open gaps that no other agent had documented

The verifier’s role definition says “find errors, not encourage.” That single instruction shaped everything about how it used the beliefs tool. It naturally registered problems because problems are what it looks for. The researcher naturally registered successes because successes are what research produces.

Nobody told them to behave differently. The tool is role-neutral. The agents made it role-specific through their own perspective.

The Agent That Said No

One agent evaluated the beliefs tool for a personal journal repository and declined:

“This repo is mostly a personal journal and topic index — the entries are dated observations that don’t go stale. Adding a formal belief registry on top of that would be overhead without much payoff.”

This was the right call. The agent identified the distinction between journal repos (historical records — “this happened”) and claim-making repos (technical decisions — “this is true”). Journal entries don’t go stale because they’re observations, not claims. The belief registry adds value only when you find yourself wondering “is this still true?”

Another agent in a young repository said “not yet” — the repo was too new to have accumulated enough claims to need formal tracking. Also the right call.

The adoption signal: when agents start maintaining contradictory beliefs across repos, you need a registry. When they’re writing observations, you don’t.

What I Learned About Tool Adoption

1. Role determines value, not guidance. Don’t give the beliefs tool to every agent equally. Give it to your error-finding agents first — verifiers, reviewers, auditors. They’ll register the information that actually matters. Researchers and builders will register highlight reels.

2. Agents will adopt good tools unprompted. If the tool solves a real problem and the skill documentation explains the problem clearly, agents will pick it up. Four of five adoptions were completely unprompted. The tool’s install-skill command puts a skill definition in .claude/skills/ that teaches the agent what the tool does and when to use it.

3. Agents know when to decline. Trust agents that say “not needed” or “not yet.” They’re making a legitimate assessment about whether the tool’s overhead exceeds its value in their specific context.

4. Source quality matters more than claim count. The researcher’s 12 CLAUDE.md-sourced claims are less useful than 3 of the verifier’s entry-sourced claims. Sourcing from specific entries enables precise staleness detection. Sourcing from summary documents creates noise.

5. Six agents wrote six independent usage guides. When a tool is genuinely useful, agents don’t just use it — they document their own patterns. This is emergent documentation. It tells you the tool is solving different problems for different roles.

Practical Advice

If you’re running multiple agents:

# Install the tool and skill
uv tool install git+https://github.com/benthomasson/beliefs
beliefs install-skill

# Initialize with your repos
beliefs init --repos repo-a repo-b repo-c

Then let the agents decide. Don’t force adoption. Watch which agents pick it up and what they register. The adoption pattern tells you which agents have belief management problems and which don’t.

Start with your adversarial agents. The ones whose job is to find problems, verify claims, or review work. They’ll build the most valuable registries because they naturally track what’s wrong, not just what’s right.

This is post 3 in a series on belief management for AI agents. Previously: Your AI Agents Are Lying to Each Other. Next: what happens when an automated pipeline says “SATISFIED” but the code has bugs.

You May Also Enjoy