Lazy Loading Docs for Agents

Lazy loading documentation for AI agents is a mechanism that provides coding agents with on-demand access to technical documentation without overwhelming their context window. Instead of including megabytes of text in every request, agents utilize a version-pinned local mirror and semantic search tools to retrieve only the specific information required to resolve a query.

This system relies on the ASK (Agent Skills Kit) and csp (Code Search Please) to manage a local checkout of the documentation. By leveraging a structured mirror of the official Claude Code docs, agents can perform token-efficient lookups and read individual markdown files only when necessary.

Sources: README.md:19-25, README.md:38-44, skills/claude-code-docs/SKILL.md:1-10

Architecture and Components

The system architecture is built around three main pillars: a continuous synchronization engine, a local resolution CLI, and an interception hook for real-time URL modification.

Synchronization Engine (sync.ts)

The sync.ts script acts as the backbone of the mirror, maintaining parity with the official Claude Code documentation. It treats llms.txt as the source of truth, rebuilding the local docs/ directory from scratch on every run. This ensures that additions, changes, and deletions are accurately reflected in the git history.

The following diagram illustrates the synchronization flow:

The sync process uses a concurrency of 10 and 3 retries per URL to ensure stability during network fluctuations.
Sources: sync.ts:1-12, sync.ts:74-95, README.md:11-17

Resolution and Search (ASK & CSP)

Agents do not access the repository directly via network requests. Instead, they use the ask CLI to resolve a version-pinned local path. If semantic search is needed, ask search delegates the task to csp, which indexes the markdown files under docs/.

Sources: README.md:21-36, README.md:40-48, skills/claude-code-docs/SKILL.md:15-35

Documentation Tooling and Hooks

To facilitate seamless access for Claude Code plugins, the project implements a PreToolUse hook. This hook intercepts WebFetch calls and modifies them before the agent performs the network request.

URL Interception Logic

The hook identifies requests to code.claude.com/docs and appends a .md extension. This forces the fetch to retrieve raw markdown instead of the full HTML application shell, saving significant bandwidth and tokens.

Link Rewriting

During the synchronization phase, internal links within the documentation are rewritten. Links that point to other mirrored pages are converted to relative filesystem paths (e.g., ../sub-agents.md), while external or unknown links are kept as canonical absolute URLs. This ensures that the documentation remains navigable even when browsed locally on platforms like GitHub.
Sources: sync.ts:18-42

Skill Implementation Flow

The SKILL.md defines how an agent should utilize the mirrored documentation to answer questions. It follows a tiered fallback strategy to ensure reliability.

1. Resolve: Use ask src to find the local docs directory.
2. Search: Attempt semantic search with csp for the top 8 relevant results.
3. Fallback Search: If csp is unavailable, use grep -ril with keyword variants.
4. Read: Load the content of the identified pages and cite using canonical URLs (e.g., mapping docs/hooks.md back to https://code.claude.com/docs/en/hooks).
5. Network Fallback: If local resolution fails entirely, fetch llms.txt directly from the web and retrieve individual .md files.

Sources: skills/claude-code-docs/SKILL.md:1-60

Summary

Lazy loading docs for agents transforms static documentation into a dynamic, local knowledge base. By combining periodic synchronization with sync.ts, path resolution via ask, and intelligent URL rewriting via PreToolUse hooks, the system ensures that AI agents have high-fidelity, low-latency access to technical information without context window bloat.