docs-ai-retrievallisted

Write documentation that AI assistants actually retrieve and cite. Generative engines never read a page — they split it into passages, embed them, and rank each passage on its own against a decomposed sub-query, so the unit of optimization is the self-contained chunk, not the page. This skill covers the two distinct stages (getting retrieved at all, then getting quoted once in context), the passage patterns that survived controlled studies, and the popular tactics that measurably backfire. Use when writing or rewriting docs so that ChatGPT, Claude, Perplexity and AI Overviews can answer from them — not for a meta-tag/structured-data audit, which is docs-seo.
Docsbook-io/docs-skills · ★ 1 · AI & Automation · score 75

Install: claude install-skill Docsbook-io/docs-skills

# docs-ai-retrieval — Writing for Retrieval, Not for Reading An AI assistant answering a question about your product does not open your page and read it. It decomposes the question into sub-queries, retrieves candidate **passages** from many pages, reranks them, fits the survivors into a context window, and generates an answer that cites some of them. Your page competes as a bag of independent chunks, several times, against passages from other sites. Two consequences drive everything in this skill: 1. **The chunk is the unit, not the page.** A section that only makes sense after reading the three sections above it loses at retrieval, because it is scored alone. 2. **There are two stages, and they pull in opposite directions.** Getting *retrieved* is a similarity problem (does this passage look like the answer to that sub-query?). Getting *cited once retrieved* is an extractability problem (can the model lift a clean claim out of it?). Optimizing only for the second one is the most common and most expensive mistake — see the warning in Step 5. --- ## What the evidence actually supports Be honest about the tiers here. Recommendations in this skill are labelled by how well they hold up, and you should be equally explicit when you report to a user. | Tier | Meaning | Examples | |---|---|---| | **Strong** | Robust across studies and engines | Topical relevance and position dominate everything else; passage-level competition; self-contained chunks | | **Moderate** | Real but