AGENT SKILL

ask

Answer grounded questions about the codebase (onboarding / Q&A) using the reviewer RAG + code graph. Use when the user asks how the code works, where something lives, or to explain a subsystem ("where is auth", "how does X work", "explain the indexing flow", "как устроено…", "где у нас…", "объясни код"). Requires a built base index + graph (reviewer MCP server). Not for reviewing PRs.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
ask
description
Answer grounded questions about the codebase (onboarding / Q&A) using the reviewer RAG + code graph. Use when the user asks how the code works, where something lives, or to explain a subsystem ("where is auth", "how does X work", "explain the indexing flow", "как устроено…", "где у нас…", "объясни код"). Requires a built base index + graph (reviewer MCP server). Not for reviewing PRs.

03 SKILL.md 正文

Ask (codebase Q&A)

Answer a free-text question about the codebase with a grounded response: every claim is backed by a real path:line citation, never an invented path. Built on the reviewer MCP server (hybrid RAG + code graph). This skill reads and explains; it does NOT modify code or review PRs.

Always answer the user in Russian (the project language), regardless of this file's language. Tool calls, code identifiers, and path:line citations stay verbatim.

Inputs

$ARGUMENTS — a free-text question about the code (e.g. "where is authentication", "how does index freshness work", "explain the retrieval pipeline").

Tools

<!-- include: _common/tool-usage.md --> Use the session-less tools above.

Plus the harness file tools (Read, Grep, Glob) to read source from the local clone on disk.

Pipeline

  1. Resolve repo/branch.
    • repo: git remote get-url origin → strip a trailing .git, take the last two path segments (owner/name). Pass "" to let the server use DEFAULT_REPO if origin is missing.
    • branch:

<!-- include: _common/branch-selection.md -->

Freshness check (first code question of the session only). After resolving repo/branch and ONLY on the first code question in this conversation — rely on conversation memory: if you have already checked index freshness earlier in this session, skip this — run uvx --from rag-reviewer reviewer status <path> --branch <branch> --json and read drift. If drift > 0, emit exactly one banner line, in Russian: «⚠ индекс отстаёт на N коммитов, ответ может не учитывать свежие изменения → rag-reviewer:sync-codebase». Do NOT block, reindex, ask for confirmation, or call sync_board — this is warn-only. Cost ≈ 0 Voyage (reads index_meta + local git). Fail-open: any error → skip the banner silently (Q&A is latency-sensitive).

1.5. Subsystem prior (cheap, optional). Call get_subsystem_summaries(repo, branch, query="<the user's question>"). At scale (summary count above the deploy threshold) this returns the top-k subsystems nearest the question; on small repos it returns all (back-compat). If it returns summaries, use the one matching the question's subsystem as a high-level orientation before search_codebase — this cuts exploration steps for architectural / "how does subsystem X work" questions. The summary is only a prior: every path:line you cite in the answer still comes from real code (search_codebase / Read), never from the summary text. Fail-open: empty / unavailable → skip this step and proceed exactly as before.

  1. Search. Call search_codebase(repo, "<question>", branch=…). Parse the path#fqn (path:start-end) headers to get candidate symbols (node_id) and line ranges. If the result is (ничего не найдено), go to Fallback.

    Lazy expansion (no user prompt). If the output ends with a cliff/rails note reporting a high-scoring tail beyond the cut AND the question looks broad, you MAY re-call search_codebase once with a higher ceiling (pass top_k=<bigger>), then merge. Do this silently — never pause to ask the user.

  2. Expand (only as needed). For an architectural / "how does X work" question, DEFAULT to skipping the graph tools (related_symbols / callers / definition) — the hybrid search usually suffices; CLAUDE.md / README are cheap priors to consult first. Only when the answer genuinely needs call relationships, for the symbols most relevant to the question, call related_symbols / callers / definition to follow the graph. Do NOT expand everything — only what the answer requires. Stop once you can answer.

  3. Confirm source. search_codebase snippets are line-numbered, so when the returned snippet already shows the exact code you cite, you may cite path:line directly from the tool output — a separate Read is not required for grounding. Use Read only when the snippet was truncated ([...truncated]) or you need surrounding context. Never cite a path:line not present in any tool output.

  4. Answer (adaptive), in Russian.

    • Default (focused question): a direct answer in 2–4 sentences, then an Evidence list — each item path:line + a one-line "why this is relevant".
    • Broad question ("explain subsystem X"): expand into sections — Краткий ответ / Ключевые символы / Поток / Связанные места — each claim still carrying a confirmed path:line.

Grounding contract (hard rule)

Cite ONLY paths that were returned by a tool AND confirmed by the tool's line-numbered output or a Read. Never invent or guess a path or line number. If you cannot ground a statement, say so explicitly instead of fabricating a citation. This is the skill's acceptance criterion.

A line-numbered search_codebase snippet that contains the cited code counts as grounding — an extra Read of the same lines is redundant.

Fallback (fail-open)

If the reviewer MCP server is unreachable or returns (ничего не найдено) / (граф недоступен) (Postgres/Neo4j/index down), degrade gracefully:

  • Use the harness Grep/Glob/Read over the local clone to locate and confirm code.
  • Tell the user (in Russian) that semantic/graph search was unavailable and the answer comes from a lexical search, so it may be less complete. Never abort — always return the best grounded answer you can.

Notes

  • Precondition: the base index + graph must be built (reviewer index). Graph precision depends on the backend: SCIP → IMPLEMENTS + accurate CALLS; tree-sitter → CALLS by name only.
  • Read-only: this skill never edits code and never posts to GitHub. Posting a human-facing review guide to a PR is a separate skill (PRI-119).

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k