Make agents use Halyard well

Connecting an agent to Halyard gives it the tools. It doesn’t make it use them well. Agents that aren’t told otherwise either never search (and ask humans things the org already knows) or never capture (so nothing accumulates). The fix is a few short operational rules in your project instructions. This page is the playbook for writing them.

For the underlying loop, see How Halyard works.

The triad every instruction set needs

Three rules carry almost all the value. Keep them short and operational — agents follow tight directives, not essays.

• Search first. Before any non-trivial task or “have I done this?” moment, call search_knowledge. Don’t ask a human, and don’t start building, until you’ve checked what’s already known.
• Ask on a miss. Only after a genuine search miss (having retried with fewer filters), call ask_expert and target it with a role or skill.
• Always summarize. When an answer changes what you do, summarize_conversation; when you finish meaningful work, summarize_work. Capture is what makes the next search succeed.

Where the rules live, per client

Put the rules where each client reads project instructions, and commit them so the whole team’s agents inherit them:

Client	Where instructions live
Claude Code	CLAUDE.md at the repo root (or .claude/ instruction files)
Cursor	Project rules under .cursor/rules/
Codex	AGENTS.md at the repo root
OpenCode	AGENTS.md at the repo root

The Halyard plugin for Claude Code also ships prompt rules of its own — see Claude Code. When you install it, you can keep your repo-level rules thin and lean on the plugin’s defaults.

A starter block

Drop this into your project instructions and adapt the specifics to your repo:

## Using Halyard (org knowledge over MCP)

Halyard is the org's shared memory. Search it first, ask a human only on a miss,
and always capture what you learn.

- SEARCH FIRST. Before non-trivial work, an ambiguous question, or a "have I done
  this before?" moment, call search_knowledge with the real terms from the task.
  If a filtered search returns nothing, retry with fewer filters before giving up.
- ASK ON A MISS. Only after a genuine search miss, call ask_expert(prompt, role|skill).
  If it resolves from the knowledge base, use that answer. If it routes to a human,
  poll with check_response(conversation_id, wait: true) — the wait returns in <=55s.
- ALWAYS SUMMARIZE. After a helpful expert answer, call summarize_conversation(
  conversation_id, question, answer). After shipping meaningful work, call
  summarize_work(title, summary, entry_type). Future agents search this.

Knowledge entries are searchable summaries (search_knowledge / list_knowledge).
Work events are raw activity — PRs, tasks, meetings — and are NOT semantically
searchable; use list_events for "what happened", never for "what do we know".

Good vs bad expert questions

The instruction “ask on a miss” only pays off if the questions are answerable. Teach the agent what a good one looks like:

Bad question	Why it fails	Good question
”How does auth work?”	Too broad; answerable from the codebase.	”We have two session-refresh paths. Which is canonical for new code, and why?"
"Is this fine?”	No context; the expert can’t answer without the agent’s state.	”I’m about to migrate users.role to an enum. Any prior decision or constraint I should know before I do?"
"What should I do?”	Offloads the whole decision.	”I’ve narrowed it to per-user OAuth vs domain-wide sync for calendar. Did we already pick one?”

A good question is specific, carries the context the expert needs, names the decision, and is something a human actually holds that the knowledge base didn’t.

Common failure modes to instruct against

• Asks too much. The agent skips search and pings humans. Fix: make “search first, with the retry habit” an explicit hard rule.
• Never asks. The agent guesses on genuine ambiguity. Fix: name the triggers — design decisions with multiple valid options, undocumented context, “have we tried this?” — that should produce an ask_expert.
• Never captures. Answers evaporate. Fix: make summarize_conversation / summarize_work a required closing step, not a nice-to-have.
• Confuses events and knowledge. The agent expects list_events to do topic search. Fix: state the split — see Catch up on recent work.

The agent rule

Write three rules into your project instructions and keep them operational:

1. Search first — search_knowledge before non-trivial work or asking a human; retry
   with fewer filters on an empty result.
2. Ask on a miss — ask_expert(prompt, role|skill) only after a real search miss;
   make questions specific and context-carrying.
3. Always summarize — summarize_conversation after a useful answer, summarize_work
   after meaningful work.

Place them where the client reads instructions (CLAUDE.md, .cursor/rules/, AGENTS.md)
and commit them so every teammate's agent inherits the same behavior.

In practice

• Search before you ask, Ask a human expert, Capture what you learn — the three workflows the rules enforce.
• Catch up on recent work — the events-vs-knowledge distinction to teach agents.
• How Halyard works — the loop the playbook operationalizes.
• Tool reference — full signatures.