Agent Skill Resolution Logic
Relevant source files
The following files were used as context for generating this wiki page:
Agent Skill Resolution Logic defines how coding agents interact with and retrieve information from the claude-code-docs mirror. This system allows agents to avoid large context overhead by resolving documentation requests through a local, version-pinned mirror using the Agent Skills Kit (ASK).
The logic facilitates lazy, on-demand access to documentation pages rather than including the entire documentation set in the initial context window. It employs a multi-tiered resolution strategy starting from local cached checkouts and falling back to live web fetches when necessary.
Sources: README.md:21-25, skills/claude-code-docs/SKILL.md:1-10
Skill Invocation Architecture
The core of the skill resolution lies in the interaction between the ask CLI and the claude-code-docs repository. When an agent invokes the /claude-code-docs skill, it triggers a structured resolution process to find the most relevant documentation.
Resolution Tiers
The resolution logic follows a prioritized hierarchy to ensure information is retrieved even in constrained environments:
- Local Cache Resolution: Uses
ask srcto locate a version-pinned local checkout. - Semantic Search: Utilizes
csp(Code Search Please) for token-efficient search over markdown files. - Keyword Fallback: Defaults to
grepif semantic search tools are missing. - Remote Fallback: Uses
WebFetchto retrieve content directly from the canonical source if local tools fail.
Sources: skills/claude-code-docs/SKILL.md:15-51, README.md:41-55
Data Flow Diagram
The following diagram illustrates the flow from a user question to a documentation-grounded answer.
Local Source Resolution
The system relies on the ask CLI to manage the lifecycle of the documentation mirror. The ask src command is the primary method for resolving the filesystem path of the documentation.
| Tool/Command | Function | Fallback Method |
|---|---|---|
ask src | Resolves the root of the cached checkout (clones on first use). | npx -y @pleaseai/ask src ... |
ask docs | Resolves the specific docs/ subdirectory within the mirror. | N/A |
ask add | Appends the documentation source to ask.json for project-wide use. | N/A |
Sources: README.md:26-36, skills/claude-code-docs/SKILL.md:18-28
Search and Selection Logic
Once the documentation path is resolved, the agent must identify relevant pages. The logic prioritizes semantic search to handle natural language queries effectively.
Semantic Search (csp)
The csp search command indexes the markdown files under the docs/ directory. By targeting the docs/ folder specifically, it avoids indexing the massive llms-full.txt file, which would lead to duplicate results and token waste.
Sources: README.md:41-50, skills/claude-code-docs/SKILL.md:30-40
Keyword Filtering
When semantic search is unavailable, the system utilizes grep -ril to scan for keyword variants. Additionally, agents are instructed to read llms.txt (the manifest) as a secondary method to shortlist pages based on one-line summaries.
Sources: skills/claude-code-docs/SKILL.md:42-48
URL Rewriting and Tool Interception
A critical component of the skill logic is the PreToolUse hook. This logic intercepts WebFetch calls to ensure the agent receives clean markdown instead of the standard HTML app shell from the documentation site.
Hook Execution Flow
The hooks/hooks.json configuration defines a command-based hook that triggers before the WebFetch tool is executed.
URL Transformation Logic
The transformation script (rewrite-docs-url.sh) performs the following operations:
- Strips fragments (
#) and query parameters (?). - Ignores URLs that already have file extensions (e.g.,
.md,.txt,.png). - Appends
.mdto valid documentation page paths. - Returns a
permissionDecision: "allow"to bypass additional user prompts.
Sources: hooks/rewrite-docs-url.sh:12-40, hooks/rewrite-docs-url.test.sh:15-25
Mirror Sync and Integrity
The resolution logic depends on the integrity of the local mirror, which is maintained by sync.ts. The sync process ensures that the local docs/ tree exactly matches the canonical manifest.
Sync Operations
- Manifest as Truth:
llms.txtis used to determine which pages should exist. - Link Rewriting: Cross-links between documentation pages are rewritten from site-absolute paths (e.g.,
/en/sub-agents) to relative markdown paths (e.g.,../sub-agents.md) so they function correctly in a local checkout or on GitHub. - Safety Checks: The sync process aborts if fewer than 10 pages are found in the manifest to prevent accidental mass deletions.
Sources: sync.ts:1-25, sync.ts:60-65
Conclusion
The Agent Skill Resolution Logic provides a robust framework for AI agents to query documentation efficiently. By combining local caching, semantic search, and automated URL rewriting, it ensures that agents always have access to canonical markdown content while minimizing latency and token consumption. This multi-layered approach guarantees functionality across different environments, from fully-featured developer setups to restricted sandbox shells.