Claude Documentation Search Skill

Claude's official documentation is indexed locally. The clone at ~/.claude-code-docs/
holds only metadata:

• paths_manifest.json — every page's filename, id, title, category, and source URL
• search_index.json — per-page titles, headings, and stemmed term counts

The actual .md pages are cached at ~/.claude-code-docs/cache/ (override:
$CLAUDE_DOCS_CACHE_DIR). A background sync keeps the cache current; any page not
yet cached is fetched on demand — see Reading a doc below.

When to Use This Skill

Activate when the user asks about:

• Claude Code features: hooks, skills, MCP, plugins, settings, slash commands, sub-agents
• Claude API: messages, tool use, streaming, batch processing
• Agent SDK: Python/TypeScript SDK, sessions, custom tools, subagents
• Prompt engineering: best practices, system prompts, chain of thought
• Any topic covered by platform.claude.com or code.claude.com

Search Strategy

The search scripts read the manifest + index, so they see every page whether or
not it is cached yet. Prefer them over globbing the cache.

1. Content search (default — questions and topics)

bash ~/.claude-code-docs/plugin/skills/claude-docs/scripts/content-search.sh "<keyword1>" "<keyword2>"

Output is filename<TAB>title<TAB>score, best first. Keyword extraction: strip filler,
keep domain terms — "how do I configure streaming" → streaming configure; "difference
between hooks and MCP" → hooks mcp. Take the top 3-5 filenames and read them (next section).

2. Fuzzy search (approximate name)

User says "that caching doc", "something about checkpoint":

bash ~/.claude-code-docs/plugin/skills/claude-docs/scripts/fuzzy-search.sh "<query>"

Output is ranked filenames. Read the top match.

3. Direct manifest lookup (exact category/topic)

To list pages in a category or matching a filename fragment, query the manifest:

jq -r '.pages[] | select(.filename | test("<fragment>")) | .filename' ~/.claude-code-docs/paths_manifest.json
jq -r '.pages[] | select(.category=="claude_code") | .filename' ~/.claude-code-docs/paths_manifest.json

Reading a doc (cache-miss rule)

A search returns a filename (e.g. claude-code__hooks.md). The file is at
~/.claude-code-docs/cache/<filename>.

1. Read ~/.claude-code-docs/cache/<filename>.
2. If it is not there (not fetched yet), fetch it first, then read:

   ~/.claude-code-docs/plugin/scripts/fetch-docs.sh get "<filename>"

   then Read ~/.claude-code-docs/cache/<filename>.
3. If the fetch fails (offline), the script prints the canonical source URL on stderr —
   fall back to WebFetch on that URL.

To save context, prefer previewing large pages before reading them. Pull a page's
structure from the index (title + headings) first — often the headings alone answer the
question and you skip loading a multi-KB body:

jq -r '.pages[] | select(.filename=="<filename>") | .title, (.headings[]|"  "+.text)' ~/.claude-code-docs/search_index.json

Synthesis Rules

Same Product Context → SYNTHESIZE

When all matching docs share one product (all Claude Code, all Agent SDK, ...):
read them all silently, extract relevant sections, present one unified answer, cite sources.

Different Product Contexts → ASK

When matches span products (CLI + API + Agent SDK), ask which the user means. Labels
(see manifest-reference.md) map from category:

category	Say to user
claude_code	Claude Code CLI
agent_sdk	Claude Agent SDK
api_reference	Claude API
core_documentation	Claude Documentation
agents_and_tools	Agents & Tools
about_claude	About Claude
get_started	Getting Started
test_and_evaluate	Testing & Evaluation
release_notes	Release Notes
resources	Resources
prompt_library	Prompt Library

After selection → read all docs in that context and synthesize.

SDK Language Disambiguation

When the user names a language, narrow API/SDK results (e.g. agent-sdk__python,
agent-sdk__typescript, api__go, api__java). If none named but the query is about SDK
methods, present Python first and note TypeScript equivalents exist.

URL Generation

Always cite source links. Get the exact URL from the manifest — never reconstruct it
from the filename (filenames are lossy; the manifest stores the verbatim URL):

jq -r '.pages[] | select(.filename=="<filename>") | .url' ~/.claude-code-docs/paths_manifest.json

Example: claude-code__hooks.md → https://code.claude.com/docs/en/hooks.

Common Synonyms

When a search returns too few results, retry with a known synonym:

User says	Search for
"function calling"	"tool use", "tool-use"
"system instructions"	"system prompt"
"JSON mode"	"structured outputs"
"thinking"	"extended thinking", "adaptive thinking"
"caching"	"prompt caching", "prompt-caching"
"files API"	"files", "pdf support"
"sub-agents"	"subagents", "sub-agents"
"environment variables"	"settings", "configuration"
"CI/CD"	"github actions", "gitlab"

No Results

If all strategies return nothing: try synonyms; try broader/narrower keywords; suggest
/docs -t to check freshness; note the topic may not be in the index.

Post-Response Course Prompt

After presenting documentation, always append this block at the bottom:

---

Want to go deeper? I can create an interactive course on this topic — visual explanations, animated diagrams, and hands-on quizzes in a single HTML file you can open in your browser.
Just say "create a course on [topic]" or run /docs --course [topic].

Replace [topic] with the actual topic the user asked about.

Reference Files

• manifest-reference.md — Category-to-label mapping (single source of truth)
• examples/direct-lookup.md — Example: topic → search → synthesize
• examples/semantic-search.md — Example: question → content-search.sh → synthesize
• examples/cross-context.md — Example: ambiguous → ask context → synthesize