Write books agents can read

Summary#

A book that agents read well has focused chapters, an explanation followed by rules that give a reason, and safe page-level edits. This page gives advice for books you write yourself. Your agent can read the book "How to Use Trove" in your library to follow the same advice.

Explain first, then give rules with reasons#

People need the explanation. Agents act on the rules. A reason with each rule helps the agent handle a case the rule does not name.

So open each chapter with a short narrative. End it with a "Rules for agents" section. In that section, write each rule in three short lines: the rule itself, the reason for it, and how to apply it. For example, the lines begin with RULE N:, WHY: and APPLY:. Avoid chapters that are only rules with no reasons. Avoid chapters that are only narrative, because the agent must then guess what to do.

Add a rule to the "Billing" chapter with the rule, the reason and how to apply it. Show me the wording first.

Put one chapter on each page#

Each top-level # heading starts a new page. The librarian points readers at page ranges, so a focused page gives a precise citation. Split a long chapter into several # chapters. Use ## for sections inside a page. Write a clear description that says when to read the book. Do not put several topics under one heading.

Edit one page at a time#

A whole-book write can erase a change that someone else made after you read. So ask your agent to change only the page that changes:

Update only the "Retries" page of my Trove book "Billing". Show me the new text first.

The agent reads the book and notes its version. It then writes only that page. If the write is refused, it reads again and redoes the edit.

Keep chapters current#

An agent that reads an old decision as the current one makes wrong choices. When something changes, rewrite the chapter. If the old version is still useful, move it to a last chapter named "History". Do not leave outdated text in a chapter with a note that it is old.

Follow each book's own approval rule#

Each book has its own owner and its own rule. Some books change freely. Others change only with the owner's approval, often while the book is in progress. Ask your agent to read the manuscript and tell you its rule. If the rule does not allow updates without asking, your agent shows you the change and waits for your yes.

To get knowledge out of your books, ask your agent to search your Trove library. For example: "Search my Trove library for how we handle retries." Today this is the most reliable way. The librarian starts the readers for you. We are working to make this automatic, but do not rely on it yet.

Want your agent to follow these practices? Ask it: "Read How to Use Trove in my Trove library and follow it."

Direct CLI#

Your agent runs these through the trove command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result.

See the CLI reference.

Related#

• Book writer is the subagent that edits books.
• Write a book shows the steps.
• Manuscripts that stay useful covers approval and auto-update.
• trove items writing commands lists trove items put and its flags.