query

Query

Find wiki pages relevant to a question. This skill is a thin wrapper around the knowledge_search MCP tool: it issues the search, then leaves synthesis to Claude using the returned candidates.

Steps

1. Parse the argument

$ARGUMENTS is the user's question. If it contains a --scope <category> token, peel that off and use it as the scope argument; otherwise leave scope unset to search all categories.

Scope can be any wiki subdirectory name (e.g. concepts, entities, learnings). Omit to search all directories.

2. Call knowledge_search

knowledge_search(query: "<question>", scope: "<optional category>")

The tool returns a JSON object of the shape:

{
  "candidates": [
    { "path": "/home/.../wiki/learnings/2026-04-29-counting-pipeline.md", "score": 3, "first_lines": "# Counting pipeline fallback gotcha\n..." }
  ]
}

candidates is ranked by BM25 score (highest first, field-weighted: title 3x, description 2x, tags 2x, body 1x), capped at 8 results, and may be empty.

3. Read the top candidates

For each candidate (in score order, up to ~3), read the full file with the Read tool. The first_lines snippet is just a hint — the full page often contains the answer the snippet doesn't show.

4. Synthesize an answer

Write a focused response that:

• Cites each wiki page used: e.g. According to [[counting-pipeline-redundant-fallback]]…
• Synthesizes across multiple candidates when more than one is relevant
• Acknowledges gaps explicitly: "The wiki doesn't cover X — here's what I can offer from general knowledge."
• Is honest about confidence: low-score matches (score 1) are often noise.

5. On empty candidates

If candidates is empty:

1. Tell the user the wiki has no coverage for this question.
2. Offer two follow-ups: (a) answer from general knowledge with that caveat, or (b) suggest they pin the answer with /second-brain:improve after the conversation so the next query hits a wiki page.

Do not silently fabricate citations — if the wiki has nothing, say so.

Notes

• This skill never writes to the wiki. Wiki growth happens via /second-brain:improve (proposes pins), the archive_to_wiki MCP tool (graduates resolved entries from PROJECT.md), and the Stop-hook auto-extractor (creates/updates wiki pages from session content).
• Search uses BM25 scoring with frontmatter field weighting. It reads full page content, so terms deep in a page still match. Date tokens (YYYY, MM, DD) are filtered from scoring.
• If the wiki has an index.md, consider reading it first to browse available pages by category before searching — useful when the question is broad.
• No re-indexing step is needed for search — knowledge_search reads the wiki tree on every call. The index.md catalog is regenerated by knowledge_reindex or after wiki writes.