117 added, 51 removed. Audit A to A.
---
name: claude-code-docs
- description: Search the Claude Code documentation via Miyo (local semantic search). Use when asked about Claude Code features, configuration, hooks, permissions, settings, MCP, plugins, skills, sub-agents, Agent SDK, CLI flags, env vars, cloud providers, or IDE integrations.
- when_to_use: Any question about how Claude Code works, how to configure it, or what features exist. Prefer over WebFetch against docs.anthropic.com — the local index is fresher and rate-limit-free.
- disable-model-invocation: false
+ description: Look up Claude Code documentation in the local Miyo-indexed folder labeled `claude-code` (resolved at runtime via Miyo — no hardcoded filesystem path, works on macOS/Windows/Linux). Use when answering questions about Claude Code — features, configuration, hooks, permissions, settings, MCP, plugins, skills, sub-agents, Agent SDK, CLI flags, slash commands, env vars, cloud providers, or IDE integrations.
+ disable-model-invocation: true
---
- # Claude Code Documentation
+ # Claude Code Documentation (local Miyo mirror)
- Semantic search over the official Claude Code documentation via Miyo
- (local Jina v5 Nano embeddings + reranking). The corpus is the
- `claude-code-docs` folder indexed in Miyo — point Miyo at
- `~/claude-code-docs/` (the docs are flat in that directory; a launchd
- job keeps the folder in sync with the upstream git repo every hour).
+ A local Markdown mirror of the official [Claude Code docs](https://code.claude.com/docs)
+ (~150 pages from `code.claude.com`, plus the release changelog), indexed in **Miyo**
+ under the folder label **`claude-code`**. The docs are in **English** — phrase Miyo
+ queries in English for best recall.
- ## How to query
+ > This skill is **manual-only** (`disable-model-invocation: true`): nothing loads into
+ > context until you invoke it with `/claude-code-docs`. Drop a copy at
+ > `~/.claude/skills/claude-code-docs/SKILL.md` for it to be available in every chat at
+ > zero idle context cost. Remove that frontmatter line in a project copy if you want
+ > Claude to auto-invoke it there.
- Always call `mcp__miyo__search` with `folder_path: "claude-code-docs"` so
- results stay scoped to the Claude Code docs and do not leak from other
- indexed folders.
+ ## Access is portable — never hardcode a filesystem path
+ This skill addresses the docs **only through Miyo's folder label `claude-code`**, not
+ through any absolute path. Miyo resolves the physical location on whatever machine it
+ runs (macOS/Windows/Linux), so the skill is portable.
+
+ - **Verify the folder exists** (and confirm its exact label) with
+ `mcp__miyo__list_folders` — you should see `claude-code (… files, ready)`. If on some
+ machine it was indexed under a different label, use that label everywhere below.
+ - **All file paths are Miyo-relative**, of the form `claude-code/<file>.md` — exactly as
+ returned by `mcp__miyo__search` / `mcp__miyo__list_files`. Pass those same relative
+ paths straight to `mcp__miyo__read_file`; **do not** prepend a mirror root and **do
+ not** use the native `Read` tool (that would need an OS-specific absolute path and
+ break portability).
+
+ ## File naming
+
+ The mirror is a **flat** folder. Nested doc URLs flatten with `__` as the separator:
+
+ - `code.claude.com/docs/en/hooks` → `claude-code/hooks.md`
+ - `code.claude.com/docs/en/agent-sdk/skills` → `claude-code/agent-sdk__skills.md`
+
+ So a whole topic family shares a filename prefix — every SDK page is `agent-sdk__*.md`.
+
+ ## How Miyo retrieval works (build better queries)
+
+ Miyo search is **hybrid**: for every query it runs two retrievers and fuses them with
+ **RRF** (Reciprocal Rank Fusion), then applies a **literal-match boost** (an exact query
+ substring in the title, then in the body, is pushed up):
+
+ - **Dense (semantic)** — embeds the query, matches by meaning. Good on paraphrase, weak
+ when your wording is far from the docs' actual terms.
+ - **BM25 (lexical)** — keyword match. Good on exact terms/jargon, blind to synonyms.
+
+ A hit must surface in **at least one** retriever's prefetch to appear at all — RRF only
+ ranks what was already pulled. So the usual failure is **recall, not ranking**: if
+ neither semantic nor keyword catches it, raising `limit` or reranking won't help.
+
+ Query rules that follow from this:
+
+ - **Use Claude Code's own vocabulary** ("PreToolUse hook", "permission mode", "MCP
+ server", "subagent", "settings.json", "output style") rather than a casual paraphrase —
+ this feeds BM25 and aligns the dense vector simultaneously.
+ - **Name the exact term** you expect in the doc (a setting key, CLI flag, hook event,
+ env var) — the literal boost rewards an exact substring.
+ - **If the first query misses, reformulate** with different/added domain terms or fire
+ 2–3 variants; don't just bump `limit`.
+ - Do **not** prepend instruction-style prefixes (e.g. `Instruct: …`) — Miyo embeds the
+ query text verbatim and symmetrically with documents, so that only adds noise.
+
+ ## Search the whole docset
+
+ Use Miyo semantic search scoped to the folder:
+
```
mcp__miyo__search(
query: "<natural-language question>",
- folder_path: "claude-code-docs",
+ folder_path: "claude-code",
limit: 5 # 3–8 is usually enough; raise for broad topics
)
```
- The tool returns ranked chunks with file paths and the snippet that matched.
- For most questions the snippets answer directly — synthesize an answer and
- cite source files inline as `[filename.md](~/claude-code-docs/<filename>.md)`.
+ ## Search a specific topic
- ## When to read the full file
+ Add the `path` filter (case-insensitive **substring** on the result path) to narrow to
+ one topic. The corpus is flat, so `path` matches a **filename fragment** — use the slug
+ prefix, no slashes:
- Fetch the raw file only if the chunk does not contain the exact detail
- needed — typical reasons:
+ ```
+ # Agent SDK pages only
+ mcp__miyo__search(query: "...", folder_path: "claude-code", path: "agent-sdk", limit: 5)
- - exact JSON schema, YAML frontmatter, or config example
- - precise CLI flag spelling or option list
- - the full table of an env-var / settings / hook event reference
+ # Hooks
+ mcp__miyo__search(query: "...", folder_path: "claude-code", path: "hooks", limit: 5)
- To read the raw file, use the **Read** tool with the absolute path:
+ # MCP
+ mcp__miyo__search(query: "...", folder_path: "claude-code", path: "mcp", limit: 5)
+ ```
+ ⚠️ **`path` must be a single fragment with no slash.** Miyo stores the folder prefix with
+ the OS-native separator (`\` on Windows, `/` on macOS/Linux), so a filter containing a
+ separator silently matches nothing on the wrong OS. Match the filename slug alone (e.g.
+ `path: "settings"`, `path: "permissions"`).
+
+ Miyo returns ranked chunks with file paths and the matched snippet. For most questions
+ the snippets answer directly — synthesize and cite source files inline by their
+ Miyo-relative path, e.g. `[hooks.md](claude-code/hooks.md)`.
+
+ ## When to read the full file
+
+ Fetch the raw file when the search chunk lacks the exact detail — an exact JSON schema,
+ YAML frontmatter, precise CLI flag spelling, or a full env-var / settings / hook-event
+ reference table.
+
+ Pass the **Miyo-relative path** that search/`list_files` returned straight to
+ `mcp__miyo__read_file` — no path rewriting, fully portable:
+
```
- Read("/Users/<you>/claude-code-docs/<filename>.md")
+ mcp__miyo__read_file(file_path: "claude-code/<file>.md")
```
- Miyo returns paths like `claude-code-docs/<filename>.md` — drop the
- `claude-code-docs/` prefix and prepend `~/claude-code-docs/`.
-
- Do **not** use `mcp__miyo__read_file` for large docs — it returns the whole
- file as one blob and gets truncated by the harness. Use Read with
- `offset`/`limit` for surgical section reads instead.
+ Some Claude Code pages are large (the CLI, settings, and hooks references especially).
+ `mcp__miyo__read_file` returns the whole file as one blob and can be truncated by the
+ harness — if that happens, lean on the search chunks (raise `limit`, or add a `path`
+ filter) to pull just the relevant sections instead.
## Anti-patterns
- - Do **not** call `mcp__miyo__search` without `folder_path: "claude-code-docs"`
- — results will include unrelated indexed folders.
- - Do **not** read raw docs first to "find" something — search first, read
- only when search results lack a specific detail.
- - Do **not** use `WebFetch` against `docs.anthropic.com` — the local index
- is fresher (CI updates upstream every few hours; launchd syncs the local
- mirror hourly) and avoids rate limits.
+ - Do **not** call `mcp__miyo__search` without `folder_path: "claude-code"` — results
+ will leak in from other indexed folders.
+ - Do **not** read raw docs first to "find" something — search first, read only when a
+ chunk lacks a specific detail.
+ - Do **not** use `WebFetch` against `code.claude.com` — the local mirror is fresher and
+ rate-limit-free.
## Sub-commands the user may invoke
### `/claude-code-docs <question>`
- Search Miyo with the question. Synthesize an answer from the top 3–5 chunks
- and cite source files.
+ Search the whole docset (`folder_path: "claude-code"`). Synthesize an answer from the
+ top 3–5 chunks and cite source files.
- ### `/claude-code-docs explain "<concept>"`
- Run a broader search (`limit: 10`), group hits by file, and explain the
- concept covering: definition, configuration, related features, gotchas.
+ ### `/claude-code-docs <topic> "<question>"`
+ Search scoped to a `path` fragment — e.g. `sdk` → `path: "agent-sdk"`, `hooks` →
+ `path: "hooks"`, `mcp` → `path: "mcp"` (single fragment, no slash).
- ### `/claude-code-docs path "<A>" "<B>"`
- Two searches — one per concept — then explain how they relate based on
- overlap and any cross-references in the matched chunks.
+ ### `/claude-code-docs explain "<concept>"`
+ Broader search (`limit: 10`), group hits by file, and explain the concept covering:
+ definition, configuration, related features, gotchas.
### `/claude-code-docs` (no args)
- Show what's indexed:
- ```
- mcp__miyo__list_files(file_path: "claude-code-docs/", limit: 200)
- ```
- List the topics and suggest the user phrase a question.
+ List what's indexed (`mcp__miyo__list_files(file_path: "claude-code/")`, or
+ `mcp__miyo__list_folders` for the count) and suggest the user phrase a question.