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

---

🤖 The Orchestrator File Is the Cover, Preface and Table of Content

Now look at the CLAUDE.md file at the root of the Playwright scaffold. 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 CLAUDE.md article earlier in this series, this should look familiar. What's new here is the framing. These three tiers are the author's voice. Every time the agent hesitates, it consults this preface to know what kind of book it is reading.

The Skills Index is the table of contents.

| Skill          | Read When Working On       |
| -------------- | -------------------------- |
| selectors      | pages/**                   |
| page-objects   | pages/**                   |
| fixtures       | fixtures/**, tests/**      |
| api-testing    | fixtures/api/**, tests/api |
| data-strategy  | test-data/**               |
| debugging      | When a test fails          |

The agent does not read every skill on startup. It reads the index, and only the index. When a task lands, it looks at the table of contents and decides which chapter to open.

That is exactly the bookshop scan. Promise, constitution, map. Thirty seconds of reading and the agent knows whether your project belongs in its hands.

---

📖 Every Skill Is a Chapter

A great chapter does three things. It tells you why the rule exists, how to apply it step by step, and what the right and wrong code looks like. Take the selectors skill from the scaffold as a worked example.

It opens with a frontmatter description that acts as a chapter abstract:

---
name: selectors
description: Selector strategy, exploration-first workflow, locator
  priority order (getByRole > getByLabel > getByPlaceholder > getByText
  > getByTestId), and feedback/validation-message selector rules for
  Playwright page objects. Use when creating page objects, writing or
  updating locators, generating UI tests...
---

The description is what the agent reads first, before it commits to opening the chapter at all. The body opens with a WHY section called "Critical" that names the principles:

- Selector priority order is mandatory: getByRole > getByLabel > ...
- NEVER use XPath
- Exploration with playwright-cli is mandatory before writing selectors
- Every page object covering forms or CRUD must include feedback selectors

Then a HOW section breaks the work into phases:

### Phase 1: Open and authenticate
### Phase 2: Explore like a user
### Phase 3: Plan test coverage
### Phase 4: Generate selectors

Then a WHAT section shows the actual code, correct and forbidden side by side:

// ✅ Correct
page.getByRole('button', { name: 'Submit' });
page.getByLabel('Email');
page.getByText(Messages.LOGIN_ERROR);

// ❌ Forbidden
page.locator('//div[@id="test"]');
page.locator('xpath=//button[text()="Submit"]');
page.locator('.btn-primary');

And finally a See Also section that links to the appendix and to sibling chapters:

## See Also
- `page-objects` skill - POM class structure
- `playwright-cli` skill - the exploration tool
- `references/feedback-selectors-example.md` - full code pattern
- `references/troubleshooting.md` - common pitfalls

That is a chapter. Self-contained, focused on one topic, structured the way a reader's brain actually wants to consume it. The Skills article covered the what of skill files. The book pattern explains the why of the structure inside them.

---

📎 The References Folder Is the Appendix

Look at the selectors/ folder on disk and you find more than just SKILL.md.

.claude/skills/selectors/
├── SKILL.md                                      ← the chapter
└── references/
    ├── examples.md                               ← worked code examples
    ├── feedback-selectors-example.md             ← deep page-object pattern
    └── troubleshooting.md                        ← common pitfalls and fixes

The chapter mentions these files but does not contain them. They are the appendix. A reader uses them only when they are deep in the actual work, the same way you flip to the back of a textbook to grab a worked example or a lookup table.

Some skills carry heavier appendices. The skill-creator skill, for example, ships with executables alongside its references:

.claude/skills/skill-creator/
├── SKILL.md
├── agents/                  ← subagent definitions
├── scripts/                 ← runnable Python tools
├── eval-viewer/             ← HTML report generator
└── references/              ← schemas and Anthropic resources

The crucial property of the appendix is that the agent does not pay for it until it asks for it. The chapter says "for the full code pattern, see references/feedback-selectors-example.md". The agent only reads that file if the current task requires it. The token cost is zero until the moment of need.

---

🏷️ The Industry Name: Progressive Disclosure

The pre-purchase scan, the chapter, and the appendix are not just an analogy. They are the three levels of an architecture pattern that the AI tooling industry has now formally converged on.

Anthropic released the SKILL.md format in December 2025, calling it progressive disclosure. OpenAI, Google, GitHub, and Cursor adopted variants of it within weeks. By early 2026 it was the default architecture for any production agent that needs to scale beyond a handful of rules. The State of Context Engineering 2026 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.

Level	What loads	When	Token cost	Reader's moment
L1	Skill name and description from YAML frontmatter	At session start, for every skill	~100 tokens per skill	The thirty-second pre-purchase scan
L2	The full SKILL.md body	When the agent decides the skill is relevant	Under 5,000 tokens	Sitting down to study one chapter
L3	Files in references/, scripts/, assets/	When the chapter explicitly points to them	Unlimited	Flipping to the appendix mid-task

The Anthropic Claude Code documentation is the canonical reference. The four-mode Diátaxis framework is the closest cousin in the technical writing world and is worth reading if you are designing your own skills from scratch.

---

⚖️ Why It Beats the All-in-One Prompt

A reasonable question at this point is: why not stuff every rule and every example into one giant system prompt? The three loading strategies look like this side by side.

Strategy	Upfront cost	Discoverability	Capacity
Eager loading	Massive. Tens of thousands of tokens before the user types a word	Perfect. The agent knows everything	Capped by the context window
Lazy loading	Zero. Nothing is loaded	Poor. The agent does not know what exists	Theoretically unlimited, practically unusable
Progressive disclosure	Small. Only metadata is loaded	Good. Semantic index drives discovery	Effectively unlimited

Eager loading is the binder you hand a new hire on day one. They might be impressed. They will not actually read it. By the time they reach page two hundred they will have forgotten page two.

AI agents behave the same way. Long instruction files cause context rot, the documented phenomenon where rules near the bottom of a prompt get applied less consistently than rules near the top.

Lazy loading is the opposite failure mode. Nothing is loaded, so the agent has no idea your project has rules at all. It defaults to its own habits, which are not yours.

Progressive disclosure is the bookshop. Cheap on day one, deep when you need it, infinite on the shelf. This is the property that lets the scaffold ship sixteen skills today and another forty next year without the agent slowing down or losing accuracy.

---

✍️ 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 Playwright scaffold's CLAUDE.md is a working template. Strip out the parts that do not apply to your stack and replace them with your own rules.

---

🧭 The Bookshelf Mental Model

If a colleague asked you "where in this book does the rule about X live?", you should be able to answer in under five seconds. If you cannot, the book is poorly organized, not your colleague.

Apply the same test to your agent. If your agent struggles to find which rule applies to a piece of code, the failure is almost never the agent. It is the bookshelf.

Progressive disclosure works because it respects how readers actually read. A good orchestration respects how agents actually load.

The structure you choose tomorrow is the structure your agent will live with on every task next month. Write it like an author, not like a checklist.

---

🙏🏻 Thank you for reading! The book pattern is the spine of every well-behaved AI agent. The agent reads the cover, opens the chapter, flips to the appendix. Your job is to make those three moments easy. In the next article we will look at how to add a new chapter to your agent's bookshelf without breaking the ones already on it.

You can find the Public README.md file for the scaffold on GitHub: Playwright Scaffold

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

Every coffee you buy ☕ directly contributes to keeping this resource open and growing for everyone.