Integrating with Custom AI Agents

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• skills/claude-code-docs/SKILL.md
• hooks/hooks.json
• sync.ts
• hooks/rewrite-docs-url.sh
• hooks/rewrite-docs-url.test.sh

Integrating custom AI agents with Claude Code documentation involves leveraging the Agent Skills Kit (ASK) and the mirror repository structure to provide agents with contextual, on-demand access to technical documentation. This integration prevents context window exhaustion by replacing large documentation dumps (e.g., a 5MB llms-full.txt file) with lazy-loaded, semantically searchable local mirrors.

The integration utilizes a combination of CLI tools (ask, csp), specialized hooks for URL rewriting, and skill definitions that allow agents to query the documentation mirror efficiently.

Sources: README.md:20-24, skills/claude-code-docs/SKILL.md:1-5

Architecture and Tooling

The integration architecture relies on a local mirror of the documentation, which is synchronized from the official source every six hours. AI agents interact with this mirror through the ask CLI and semantic search capabilities.

Key Components

Component	Description
ASK (Agent Skills Kit)	CLI tool that manages local checkouts of documentation repositories and generates agent skills.
CSP (Code Search Please)	Utility for token-efficient semantic search over cached document checkouts.
claude-code-docs mirror	A GitHub repository tracking individual documentation pages as Markdown, providing a version-pinned source for agents.
Hooks	PreToolUse hooks that intercept agent tool calls (like WebFetch) to optimize data retrieval.

Sources: README.md:1-12, README.md:20-30, README.md:43-50

Document Synchronization Flow

The sync.ts script ensures the local mirror remains an accurate representation of the canonical docs. It uses llms.txt as a manifest to handle page additions and deletions.

Skill Integration and Local Resolution

Custom agents use specific skills to interface with the documentation mirror. These skills are defined in SKILL.md and registered via ask add.

Skill Execution Logic

When an agent needs to answer a question, it follows a multi-step resolution process:

1. Resolve Mirror Path: Uses ask src github:pleaseai/claude-code-docs to find the local path of the docs.
2. Semantic Search: Uses csp to find relevant documentation snippets within the local mirror.
3. Keyword Search (Fallback): Uses grep to find keywords if semantic search is unavailable.
4. WebFetch (Fallback): Directly fetches the canonical URL if local tools fail.

Hook-Based URL Rewriting

To improve the quality of data retrieved via WebFetch, the integration includes a PreToolUse hook. This hook intercepts requests to code.claude.com/docs and redirects them to the raw .md source files.

Hook Implementation

The hook is defined in hooks.json and executed via rewrite-docs-url.sh. It specifically targets the WebFetch tool.

{
  "matcher": "WebFetch",
  "hooks": [
    {
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/rewrite-docs-url.sh"
    }
  ]
}

Sources: hooks/hooks.json:4-15

Rewriting Logic

The shell script extracts the URL from the tool input, validates that it belongs to the documentation domain, and appends .md while stripping fragments or query parameters. This ensures the agent receives clean Markdown instead of an HTML application shell.

Original URL	Rewritten URL
.../en/agents	.../en/agents.md
.../en/hooks#anchor	.../en/hooks.md

Sources: hooks/rewrite-docs-url.sh:10-40, README.md:52-64

Implementation Details for Syncing

The sync.ts script includes a rewriteLinks function. This is critical for custom agents because it transforms site-absolute paths (used on the web) into relative file-system paths suitable for local browsing.

function rewriteLinks(content: string, rel: string, knownSlugs: Set<string>): string {
  // Logic to convert /en/slug to ./slug.md or ../slug.md
  // Also handles GitHub-specific heading ID sanitization
}

Sources: sync.ts:18-43

Summary

Integrating custom AI agents with claude-code-docs provides a robust framework for documentation access. By combining the ask CLI for lifecycle management, csp for semantic retrieval, and specific PreToolUse hooks for URL optimization, developers can ensure that agents have high-fidelity, up-to-date access to technical documentation without overwhelming the model's context window.

Sources: README.md:20-28, skills/claude-code-docs/SKILL.md:5-10