ASK CLI Commands

Relevant source files

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

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

The ask CLI (Agent Skills Kit) is a primary interface for managing and interacting with mirrored documentation within the claude-code-docs project. It allows AI coding agents to access local documentation mirrors lazily and on-demand, preventing the need to load massive amounts of text directly into the agent's context window.

The CLI facilitates repository cloning, path resolution for cached documentation, and integration with csp (Code Search Please) for semantic searching. It is designed to work as a standalone binary or via npx/bunx in environments where the CLI is not globally installed.

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

Core Command Set

The following table summarizes the primary commands used to interact with the documentation mirror:

Command	Description	Example Usage
ask src	Prints the root directory of a cached repository checkout. Clones on first use.	ask src github:user/repo
ask docs	Resolves the specific path to the docs/ subdirectory within a cached mirror.	ask docs github:user/repo
ask search	Performs semantic search over the cached mirror using csp.	ask search <repo> "<query>"
ask add	Appends a documentation repository reference to ask.json.	ask add github:user/repo
ask install	Generates AGENTS.md and required skill definitions for agents.	ask install

Sources: README.md:27-41, skills/claude-code-docs/SKILL.md:15-18

Repository Resolution and Initialization

The ask src command is critical for locating documentation files. When an agent or developer invokes this command, the CLI ensures a local copy of the repository exists in a hidden directory (typically ~/.ask/).

Resource Resolution Flow

The following diagram illustrates how the ask CLI resolves a request for a documentation source:

The CLI provides an absolute path to the local mirror, which can then be used by other tools like grep or csp.
Sources: README.md:27-33, skills/claude-code-docs/SKILL.md:15-22

Semantic Search with ask search

The ask search command leverages the csp (Code Search Please) tool to perform token-efficient semantic searches. Instead of reading every file, agents can query specific information within the documentation.

Search Execution Logic

1. Dependency Check: The CLI checks if csp is available on the system PATH.
2. Fallback Mechanism: If csp is missing, the CLI outputs a runnable recipe that the user can execute via npx.
3. Indexing: By passing the --content docs flag, the search is restricted to individual markdown files under the docs/ directory, avoiding duplicate results from the large llms-full.txt bundle.

Automated Documentation Synchronization

The sync.ts utility maintains the integrity of the documentation mirrored from code.claude.com/docs. It treats the llms.txt manifest as the source of truth, ensuring that the local mirror accurately reflects the current state of the official docs.

Synchronization Components

• Link Rewriting: A function rewriteLinks transforms site-absolute paths (e.g., /en/sub-agents) into relative file links (e.g., ../sub-agents.md) so that the documentation is browsable on platforms like GitHub.
• Concurrency Control: The script uses a concurrency limit (set to 10) and a retry mechanism (3 attempts) to handle network instability.
• Validation: The script aborts if the manifest returns fewer than 10 pages, preventing accidental mass deletions.

// Example of link rewriting logic used during sync
function rewriteLinks(content: string, rel: string, knownSlugs: Set<string>): string {
  // Logic to convert /en/slug to ./slug.md or canonical URL
  const fromDir = dirname(rel);
  // ... replacement logic ...
  return content;
}

Sources: sync.ts:13-33, sync.ts:65-71, README.md:14-19

Hook and Plugin Interaction

The project includes a Claude Code plugin that utilizes a PreToolUse hook to intercept WebFetch calls. The rewrite-docs-url.sh script automatically redirects requests for HTML documentation pages to their raw Markdown counterparts.

URL Transformation Logic

The hook identifies URLs matching https://code.claude.com/docs/* and appends .md while stripping fragments or query parameters.

Original URL	Processed URL
.../en/agents	.../en/agents.md
.../en/hooks#fragment	.../en/hooks.md
.../en/hooks?query=1	.../en/hooks.md

Sources: hooks/rewrite-docs-url.sh:15-38, hooks/hooks.json:4-15, README.md:59-70

The ask CLI and its associated tools provide a robust infrastructure for managing high-volume documentation, enabling AI agents to perform targeted searches and retrieve clean markdown content without overwhelming their context limits.