{"slug": "the-book-pattern-progressive-disclosure-for-ai-agents", "title": "📚 The Book Pattern: Progressive Disclosure for AI Agents", "summary": "AI agents should interact with project documentation using the \"progressive disclosure\" pattern, modeled after how readers approach technical books. Just as a reader first scans the back cover, preface, and table of contents before diving into specific chapters, an AI agent should use a structured file like CLAUDE.md that contains a role section (the promise), a constitution with rules (the preface), and a skills index (the table of contents). This layered approach allows the agent to quickly understand its context and find the exact information needed for a given task without processing everything at once.", "body_md": "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.\n\nYou 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.\n\nIf those three pass the test, you pay for it.\n\nLater, 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.\n\nYour AI agent should read your project the exact same way.\n\nIn 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**.\n\n## 📚 The Anatomy of a Technical Book\n\nOpen any well-written Packt, Manning, O'Reilly, or Pragmatic Bookshelf title and you will find the same three parts, every single time.\n\n**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.\n\n**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.\n\n**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.\n\nThree parts. Each loaded into the reader's mind at a different moment. Each designed for a different decision.\n\n## 🤖 The Orchestrator File Is the Cover, Preface, and Table of Contents\n\nNow look at the `CLAUDE.md`\n\nfile at the root of the [Playwright scaffold](https://idavidov.eu/the-scaffold-playwright-ai). It has the same three parts.\n\nThe **Role section** is the back cover.\n\n```\nYou are an Automation Test Architect with extensive experience in\nboth API and UI testing using Playwright. Your expertise spans\ndesigning scalable test automation frameworks, implementing type-safe\nsolutions with TypeScript and Zod, and applying best practices for\ntest isolation, maintainability, and reliability.\n```\n\nIn 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.\n\nThe **Constitution** is the preface. The scaffold splits it into three tiers borrowed from how legal systems work:\n\n```\n### MUST (Mandatory)\n\n| Dependency Injection | Use fixtures, never `new PageObject(page)` |\n| Selectors | getByRole > getByLabel > getByPlaceholder > getByText > getByTestId |\n| Type Safety | Use Zod schemas, no `any` type |\n| Strict Schemas | Always `z.strictObject()`, never `z.object()` |\n\n### SHOULD (Recommended)\n\n| Data Generation | Use Faker via factories for happy-path data |\n| Test Isolation | Independent tests, use beforeEach not shared state |\n\n### WON'T (Forbidden)\n\n| No XPath | Never use XPath selectors |\n| No Hard Waits | Never use page.waitForTimeout() |\n| No `any` | Never use TypeScript's any type |\n```\n\nIf you covered the [CLAUDE.md article earlier in this series](https://idavidov.eu/claude-md-teaching-the-ai-your-rules), 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.\n\nThe **Skills Index** is the table of contents.\n\n```\n| Skill         | Read When Working On         |\n| ------------- | ---------------------------- |\n| selectors     | pages/\\*\\*                   |\n| page-objects  | pages/\\*\\*                   |\n| fixtures      | fixtures/**, tests/**        |\n| api-testing   | fixtures/api/\\*\\*, tests/api |\n| data-strategy | test-data/\\*\\*               |\n| debugging     | When a test fails            |\n```\n\nThe 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.\n\nThat is exactly the bookshop scan. Promise, constitution, map. Thirty seconds of reading and the agent knows whether your project belongs in its hands.\n\n## 📖 Every Skill Is a Chapter\n\nA 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`\n\nskill from the scaffold as a worked example.\n\nIt opens with a frontmatter description that acts as a chapter abstract:\n\n```\n---\nname: selectors\ndescription: Selector strategy, exploration-first workflow, locator\n  priority order (getByRole > getByLabel > getByPlaceholder > getByText\n  > getByTestId), and feedback/validation-message selector rules for\n  Playwright page objects. Use when creating page objects, writing or\n  updating locators, generating UI tests...\n---\n```\n\nThe 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:\n\n```\n- Selector priority order is mandatory: getByRole > getByLabel > ...\n- NEVER use XPath\n- Exploration with playwright-cli is mandatory before writing selectors\n- Every page object covering forms or CRUD must include feedback selectors\n```\n\nThen a **HOW** section breaks the work into phases:\n\n```\n### Phase 1: Open and authenticate\n\n### Phase 2: Explore like a user\n\n### Phase 3: Plan test coverage\n\n### Phase 4: Generate selectors\n```\n\nThen a **WHAT** section shows the actual code, correct and forbidden side by side:\n\n```\n// ✅ Correct\npage.getByRole(\"button\", { name: \"Submit\" });\npage.getByLabel(\"Email\");\npage.getByText(Messages.LOGIN_ERROR);\n\n// ❌ Forbidden\npage.locator('//div[@id=\"test\"]');\npage.locator('xpath=//button[text()=\"Submit\"]');\npage.locator(\".btn-primary\");\n```\n\nAnd finally a **See Also** section that links to the appendix and to sibling chapters:\n\n```\n## See Also\n\n- `page-objects` skill - POM class structure\n- `playwright-cli` skill - the exploration tool\n- `references/feedback-selectors-example.md` - full code pattern\n- `references/troubleshooting.md` - common pitfalls\n```\n\nThat is a chapter. Self-contained, focused on one topic, structured the way a reader's brain actually wants to consume it. The [Skills article](https://idavidov.eu/skills-domain-expertise-on-demand) covered the *what* of skill files. The book pattern explains the *why* of the structure inside them.\n\n## 📎 The References Folder Is the Appendix\n\nLook at the `selectors/`\n\nfolder on disk and you find more than just `SKILL.md`\n\n.\n\n```\n.claude/skills/selectors/\n├── SKILL.md                                      ← the chapter\n└── references/\n    ├── examples.md                               ← worked code examples\n    ├── feedback-selectors-example.md             ← deep page-object pattern\n    └── troubleshooting.md                        ← common pitfalls and fixes\n```\n\nThe 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.\n\nSome skills carry heavier appendices. The `skill-creator`\n\nskill, for example, ships with executables alongside its references:\n\n```\n.claude/skills/skill-creator/\n├── SKILL.md\n├── agents/                  ← subagent definitions\n├── scripts/                 ← runnable Python tools\n├── eval-viewer/             ← HTML report generator\n└── references/              ← schemas and Anthropic resources\n```\n\nThe 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.\n\n## 🏷️ The Industry Name: Progressive Disclosure\n\nThe 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.\n\nAnthropic released the `SKILL.md`\n\nformat 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](https://medium.com/towards-artificial-intelligence/state-of-context-engineering-in-2026-cf92d010eab1) write-up captures the shift in one sentence: \"discovery first, activation when relevant, execution only during the task.\"\n\nThe three levels map cleanly onto the bookshop journey.\n\n| Level | What loads | When | Token cost | Reader's moment |\n|---|---|---|---|---|\nL1 |\nSkill `name` and `description` from YAML frontmatter |\nAt session start, for every skill | ~100 tokens per skill | The thirty-second pre-purchase scan |\nL2 |\nThe full `SKILL.md` body |\nWhen the agent decides the skill is relevant | Under 5,000 tokens | Sitting down to study one chapter |\nL3 |\nFiles in `references/` , `scripts/` , `assets/`\n|\nWhen the chapter explicitly points to them | Unlimited | Flipping to the appendix mid-task |\n\nThe [Anthropic Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/skills) is the canonical reference. The four-mode [Diátaxis framework](https://diataxis.fr/) is the closest cousin in the technical writing world and is worth reading if you are designing your own skills from scratch.\n\n## ⚖️ Why It Beats the All-in-One Prompt\n\nA 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.\n\n| Strategy | Upfront cost | Discoverability | Capacity |\n|---|---|---|---|\nEager loading |\nMassive. Tens of thousands of tokens before the user types a word | Perfect. The agent knows everything | Capped by the context window |\nLazy loading |\nZero. Nothing is loaded | Poor. The agent does not know what exists | Theoretically unlimited, practically unusable |\nProgressive disclosure |\nSmall. Only metadata is loaded | Good. Semantic index drives discovery | Effectively unlimited |\n\nEager 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.\n\nAI 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.\n\nLazy 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.\n\nProgressive 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.\n\n## ✍️ Writing Your Orchestration Like an Author\n\nHere is how to apply the pattern to your own project. Treat it as a writing brief, not a coding task.\n\n**For the orchestrator file** (`CLAUDE.md`\n\n, `.cursor/rules/`\n\n, `.github/copilot-instructions.md`\n\n):\n\n-\n**The back cover.** One short paragraph naming the agent's role and the project's domain. Resist the urge to over-explain. -\n**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. -\n**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.\n\n**For each skill chapter** (`.claude/skills/{name}/SKILL.md`\n\n):\n\n-\n**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. -\n**WHY.** A short \"Critical\" or \"Principles\" section that names the rules and explains the reasoning behind them. -\n**HOW.** Numbered phases or steps. Each phase ends with a concrete outcome. -\n**WHAT.** Code examples, labelled with ✅ and ❌. Tables for decision trees. A \"See Also\" section pointing to the appendix.\n\n**For each appendix** (`references/`\n\n, `scripts/`\n\n, `assets/`\n\n):\n\n- Things the chapter would suffer from including inline. Long worked examples, troubleshooting tables, runnable scripts, deep edge cases.\n- Always referenced by name from the chapter. An appendix the chapter never mentions might as well not exist.\n\nIf you are starting from scratch, the [Playwright scaffold's `CLAUDE.md](https://github.com/idavidov13/Playwright-Scaffold-AI-Assisted-Development-Public)` is a working template. Strip out the parts that do not apply to your stack and replace them with your own rules.\n\n## 🧭 The Bookshelf Mental Model\n\nIf 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.\n\nApply 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.\n\nProgressive disclosure works because it respects how readers actually read. A good orchestration respects how agents actually load.\n\nThe 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.\n\n🙏🏻 **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.\n\nYou can find the Public README.md file for the scaffold on GitHub: [Playwright Scaffold](https://github.com/idavidov13/Playwright-Scaffold-AI-Assisted-Development-Public)\n\nYou can get access to the private GitHub repository here: [Get Access](https://buymeacoffee.com/idavidov/e/513835)", "url": "https://wpnews.pro/news/the-book-pattern-progressive-disclosure-for-ai-agents", "canonical_source": "https://dev.to/idavidov13/the-book-pattern-progressive-disclosure-for-ai-agents-3mej", "published_at": "2026-05-22 06:56:08+00:00", "updated_at": "2026-05-22 07:01:25.749889+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools"], "entities": ["Packt", "Manning", "O'Reilly", "Pragmatic Bookshelf"], "alternates": {"html": "https://wpnews.pro/news/the-book-pattern-progressive-disclosure-for-ai-agents", "markdown": "https://wpnews.pro/news/the-book-pattern-progressive-disclosure-for-ai-agents.md", "text": "https://wpnews.pro/news/the-book-pattern-progressive-disclosure-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/the-book-pattern-progressive-disclosure-for-ai-agents.jsonld"}}