📚 The Book Pattern: Progressive Disclosure for AI Agents

You are standing in a bookshop holding a technical book you might buy. You have about thirty seconds before you decide. So you do three things.

You read the back cover to see what the book promises. You flip to the introduction to check the author's rules and how they think. You scan the table of contents to see if the parts you actually care about are in there.

If those three pass the test, you pay for it.

Later, when you sit down to read, you study the chapter that matches the problem you're solving. And later still, when you are deep in your own work, you flip back to the appendix to grab the exact example you need.

Your AI agent should read your project the exact same way.

In the previous article we sketched the three-layer model that the scaffold runs on. This article gives you the mental model that makes it stick, and the industry name for the architecture you are quietly already using - progressive disclosure.

📚 The Anatomy of a Technical Book

Open any well-written Packt, Manning, O'Reilly, or Pragmatic Bookshelf title and you will find the same three parts, every single time.

The back cover is the promise. Two paragraphs that tell you who the book is for, what it covers, and what you will be able to do after reading it. It exists so a reader can decide in thirty seconds whether the book belongs in their hands.

The preface is the author's constitution. It states the assumptions, the prerequisites, the conventions, the things you will be expected to know, and the things the book explicitly refuses to cover. It is what makes the author's voice consistent across two hundred pages.

The table of contents is the map. A flat list of chapter titles, ordered, scannable, with page numbers. It exists so that a reader who already trusts the book can find the exact part they need without re-reading everything that came before.

Three parts. Each loaded into the reader's mind at a different moment. Each designed for a different decision.

. It has the same three parts.

The Role section is the back cover.

You are an Automation Test Architect with extensive experience in

both API and UI testing using Playwright. Your expertise spans

designing scalable test automation frameworks, implementing type-safe

solutions with TypeScript and Zod, and applying best practices for

test isolation, maintainability, and reliability.

In about fifty words the agent learns who it is, what kind of project this is, and what it is expected to be good at. The agent reads this once, at the start of every session.

The Constitution is the preface. The scaffold splits it into three tiers borrowed from how legal systems work:

### MUST (Mandatory)



| Dependency Injection | Use fixtures, never `new PageObject(page)` |

| Selectors | getByRole > getByLabel > getByPlaceholder > getByText > getByTestId |

| Type Safety | Use Zod schemas, no `any` type |

| Strict Schemas | Always `z.strictObject()`, never `z.object()` |



### SHOULD (Recommended)



| Data Generation | Use Faker via factories for happy-path data |

| Test Isolation | Independent tests, use beforeEach not shared state |



### WON'T (Forbidden)



| No XPath | Never use XPath selectors |

| No Hard Waits | Never use page.waitForTimeout() |

| No `any` | Never use TypeScript's any type |

If you covered the covered the what of skill files. The book pattern explains the why of the structure inside them.

write-up captures the shift in one sentence: "discovery first, activation when relevant, execution only during the task."

The three levels map cleanly onto the bookshop journey.

The is the closest cousin in the technical writing world and is worth reading if you are designing your own skills from scratch.

✍️ Writing Your Orchestration Like an Author

Here is how to apply the pattern to your own project. Treat it as a writing brief, not a coding task.

For the orchestrator file (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md):

1. 
   The back cover. One short paragraph naming the agent's role and the project's domain. Resist the urge to over-explain.


2. 
   The preface. A three-tier constitution. MUST for non-negotiables, SHOULD for recommended defaults, WON'T for hard refusals. Write each rule in one line.


3. 
   The table of contents. A single table listing every skill, when to read it, and what it covers. Nothing else lives in this file. Detail goes downstream.

For each skill chapter (.claude/skills/{name}/SKILL.md):

1. 
   The frontmatter description. Two to three sentences that name the topic, list the triggering keywords, and pre-empt the wrong skill from loading. This is the part the agent reads first.


2. 
   WHY. A short "Critical" or "Principles" section that names the rules and explains the reasoning behind them.


3. 
   HOW. Numbered phases or steps. Each phase ends with a concrete outcome.


4. 
   WHAT. Code examples, labelled with ✅ and ❌. Tables for decision trees. A "See Also" section pointing to the appendix.

For each appendix (references/, scripts/, assets/):

1. Things the chapter would suffer from including inline. Long worked examples, troubleshooting tables, runnable scripts, deep edge cases.


2. Always referenced by name from the chapter. An appendix the chapter never mentions might as well not exist.

If you are starting from scratch, the

You can get access to the private GitHub repository here: Get Access