rag
Use when building retrieval over a project corpus (docs, code, notes), when answering chunking/embedding/vector-store questions, when evaluating whether retrieval actually works, or when an agent "can't find things in the docs" and grep alone is not cutting it.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- rag
- triggers
- [ "user", "model" ]
- description
- Use when building retrieval over a project corpus (docs, code, notes), when answering chunking/embedding/vector-store questions, when evaluating whether retrieval actually works, or when an agent "can't find things in the docs" and grep alone is not cutting it.
02 资源文件 2
- 参考文档reference/eval-and-failures.md3.7 KB
- 参考文档reference/tier-recipes.md5.2 KB
03 SKILL.md 正文
RAG
Build retrieval over arbitrary project corpora, offline-first and
provider-neutral. Evidence base: research dispatched via
.devin/ledgers/agent-docs-rag.md but the output doc was never committed;
treat C-number claims as unverified secondary sources (#530).
The tier ladder
Escalate only on measured failure of the current tier: golden-set recall/hit-rate misses, not vibes. Before tiering up, re-run the eval on the current tier - lexical tiers are stronger than assumed.
| Tier | Retrieval | Deps | Escalate when |
|---|---|---|---|
| 0 - Agentic lexical | glob/grep/read loops over the live tree | none | corpus outgrows ad-hoc exploration; repeated identical queries |
| 1 - Lexical index | BM25 over chunked corpus (SQLite FTS5 bm25(), or a BM25 pip package) |
stdlib or one pip pkg | paraphrase/synonym queries miss on the golden set |
| 2 - Local hybrid | local embeddings + in-process store + RRF fusion with BM25 + optional local cross-encoder rerank | opt-in deps | corpus/ops scale beyond local, or latency budget needs approximate indexes |
| 3 - Hosted / server | hosted embeddings or a server vector DB | consent + credentials | managed ops required; never the default |
Rationale: agentic filesystem exploration leads at small corpus scale but costs far more query tokens; a BM25 index overtakes it as corpora grow (C24). For code, index-free ripgrep-style retrieval matches graph-based RAG baselines (C26), and a shipped coding agent uses live-tree ripgrep search instead of a vector index (C28 [secondary]). A well-tuned BM25 retriever inside an agent loop can beat released dense-retriever agents (C25 [abs]).
Detailed recipes per tier: reference/tier-recipes.md.
Build order (all tiers)
- Golden set first. Before any embedding or index work, write a golden set of query -> expected-passage pairs and measure hit rate / recall@k / MRR deterministically (C18). Retrieval below a precision threshold actively degrades a coding agent, not just wastes tokens (C27 [abs]).
- Structure-aware chunking. Default: split on document structure
(Markdown headers, code language separators), then recursive
character splitting (
"\n\n" -> "\n" -> " ") as the size cap (C2). Chunking choice has significant impact on retrieval accuracy and some popular defaults perform poorly (C3); the chunking delta can exceed the embedding-model delta, so fix splitting before swapping models (C4 [single-corpus]). No strategy fits all corpora (C1); semantic chunking improves cohesion at added cost and unpredictable sizes (C5). - Provenance on every chunk. Each stored chunk carries
path:start_line-end_lineplus enough text to quote it back, matching theknowledge-modelingextracted-fact convention. Retrieval that cannot cite where a chunk came from is not shippable here. - Tier entry. Start at tier 0. Add a BM25 index (tier 1) when the
corpus is large or queries repeat; verify the target Python actually
ships FTS5 compiled in - it is a build-time, platform-dependent option -
before relying on
bm25()(C36). Hybrid + rerank (tier 2) only when the golden set shows lexical misses on paraphrase; pick embedding models from MTEB filtered by domain - code retrieval tasks exist there - never by hype (C6).
Eval-harness sketch and metric definitions: reference/eval-and-failures.md.
Failure-mode checklist
Walk this list before blaming the model (full catalog with C-numbers in
reference/eval-and-failures.md; the seven canonical failure points are
C34):
- Missing content: the answer is not in the corpus (C34).
- Missed top rank: present but retrieval never surfaces it - a recall problem, fixable by chunking/fusion, not generation (C34).
- Not consolidated: retrieved but lost among too many chunks - answer quality vs chunk count is an inverted U (C31); order best chunks at the beginning and end of context, mid-context is used worst (C33).
- Not extracted / wrong format / wrong specificity: prompt or post-processing issues, not index issues (C34).
- Stale or duplicated index entries drifting from the live tree (C34 family) - rebuild or incremental-merge with conflict reporting.
- Too much retrieved context: accuracy degrades past large retrieved volumes in most models (C32 [abs]); retrieval is chosen over long context for cost, not quality (C30).
- Agentic-loop risks: compounding errors, memory poisoning, cascading tool failures - bound the loop (C23 [abs]).
Agentic pattern
Retrieval-as-tool inside the reasoning loop is the current paradigm (C22): the agent issues search calls, reads results, refines queries. Agentic reasoning works best after ranked discovery, not in place of it (C24). Keep loops bounded and apply context-hygiene cost guards.
Teach vs omit
Teach: the tier ladder with measured escalation; golden-set eval before embeddings; structure-aware chunking; provenance; hybrid + rerank recipe at tier 2; staleness/dedup; the failure checklist.
Omit (project boundaries): vendor walkthroughs and hosted-service setup (provider-neutral per vision); any named "best" embedding model (point at MTEB - leaderboards churn); shipped runtimes, indexes, or MCP configs; GraphRAG and retriever fine-tuning (construction cost, scope); implementation code (this skill is guidance, not a runtime).
04 同仓库更多 Skills
montador-de-ideias
Use when assembling, expanding, or elevating a raw project idea or initial prompt into an ultra-detailed, first-principles dossier and compiled master prompt with journalistic OSINT market research, Tech Lead and Staff Architect justifications, atomic and modular hardening/optimization, and high-impact contact surfaces.
git-github-adaptive-engineering
Use when any task touches git history, GitHub issues/PRs/releases/CI, repo governance, or branch and merge decisions. Runs the Fase Zero situational-awareness battery, picks one of five delivery flows via the adaptive decision engine, and enforces commit/PR information-density standards. Orchestrates the gh, git-workflows, github-actions, pr, and debug/finish skills.
adaptive-agenda-calendar-routine-engine
Use when planning or executing work across hours, days, weeks, or sprints. Turns the calendar into a strict time-blocked agenda (HH:MM-HH:MM blocks carrying a routine profile, expected inputs, and a handoff output artifact), runs the 5-stage cognitive flow (Radar and Hunt -> Triage plus Steve Jobs conception -> workbench manifest -> >=32-cycle loop -> Close plus Open-Minded Scrum), and unfolds macro calendar milestones into micro agenda blocks through extensions/gcal/wrapper.py.
demo
Use when demonstrating a skill in a fixture project.
duplicate-skill
Use when testing duplicate skill name detection.
duplicate-skill
Use when testing duplicate skill name detection.