How to Build Huge Agent Knowledge Bases Without Huge Context Windows

Quick answer: A large agent knowledge base should have a small discovery layer and deeper material that loads only when relevant. Keep Skill names and descriptions short but distinctive, group references by task, scope the catalog for different workers, and measure the complete effective request rather than one “Skills” line in a context report. Progressive disclosure reduces loaded bodies; it does not make a huge catalog's discovery, bootstrap, or duplicate-representation costs disappear.

“Put all the documentation in the prompt” is the first version of a coding-agent knowledge system. It works until the repository has enough rules to become useful. Then the knowledge base starts competing with the code for the same context window.

The answer is not to choose between a smart agent and a documented repository. The answer is to give the repository an index, then load the relevant depth at the moment it is needed.

Four different context costs

Teams often talk about context as if it were one bucket. A growing Skill library usually creates several:

1. Discovery cost: names and descriptions that help an agent choose a Skill.
2. Activation cost: the body and references loaded after a Skill is selected.
3. Runtime cost: tool schemas, messages, reconnects, and other system material added by the harness.
4. Representation cost: the same semantic catalog appearing in more than one model-visible form.

Progressive disclosure directly helps with the second cost. It does not automatically eliminate the others. That distinction is important when a session feels slow or begins with a surprisingly large request before any useful code has been read.

The Claude Code Skills documentation describes this model directly: Skill names and descriptions are available for discovery, while the body loads when a Skill is used. It also documents controls for visibility and context inspection, including /doctor, /context, and skillOverrides.

Build a catalog an agent can actually search

The first layer is metadata, so metadata needs to do real work. A description such as “Helpful coding instructions” is almost indistinguishable from twenty neighbors. A better description names the trigger and the outcome:

name: android-safe-areas
description: Apply and verify the factory safe-area boundary for full-screen Android Compose UI.

Keep the description specific enough to route the task, but short enough that the catalog remains cheap to inspect. Put examples, edge cases, and long checklists in the Skill body or its reference files.

Scope knowledge by worker and task

Not every worker needs every Skill. A release worker needs store metadata and signing guidance. A code-review worker needs architectural rules and test commands. A documentation worker may need neither.

Separate catalogs by role where the tooling allows it. If it does not, use visibility controls, naming conventions, or a small routing Skill that points to the deeper material. A flat directory containing every experiment, historical compatibility note, and app-specific procedure is easy to grow and hard to retrieve from.

The same principle applies inside a Skill. Keep the entry point short, then link to a reference only after the task has established that the reference is relevant. An agent should not have to ingest the entire mobile-release manual to learn the one command needed to inspect a build.

Measure the complete request

When diagnosing context cost, do not stop at the line labelled “Skills.” Record the clean first request, the tool definitions, the initial messages, and any later reconnect or resume payloads. Compare a small known catalog with the real one, and note which parts are intentionally loaded and which are repeated by the runtime.

A recent practitioner report described one Claude Code setup where 247 Skills appeared in both tool metadata and a separate listing attachment. That is useful as a measurement lead, not as a universal claim about every session. The exact token counts depend on the release, configuration, estimator, and harness. The engineering lesson is broader: measure the effective provider request, not just the catalog you intended to configure.

A practical growth loop

Use this loop as the repository grows:

1. Start with a small, task-specific catalog.
2. Add a Skill only when a recurring failure has a clear reusable fix.
3. Give it a discriminative name and description.
4. Keep the body procedural and move long source material into references.
5. Run clean-session tasks with the Skill visible and hidden.
6. Compare success, time, and input tokens.
7. Retire, merge, or scope Skills that do not improve the work.

This prevents the knowledge plane from becoming an unbounded second application that every worker must boot before touching the first file.

The design target

The goal is not the smallest possible prompt. It is the smallest always-on prompt that can reliably route an agent to the right depth.

That gives you a durable knowledge base without pretending context is free. Keep the constitution visible, make the catalog searchable, load procedures on demand, and instrument the whole path from startup to tool call. For the root-file boundary, see why you should stop putting everything in CLAUDE.md. Once the system is stable, test the instructions themselves in CI — your CLAUDE.md needs tests too.