Julian lechnerandClaude Opus 5.5
14e6588d4e
Expose the local Qwen search as a skill with an explicit trigger for concept questions, the command for both shells, result handling, and its limits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
---
|
|
name: semantic-search
|
|
description: Use when you must find where a behavior, concept, or rule lives in a repository and do not know its identifiers or exact strings, or when a first rg search returned nothing useful. Returns ranked code and documentation chunks from the local Qwen index.
|
|
---
|
|
|
|
# Semantic Search
|
|
|
|
Search the current Git repository by meaning with the locally installed Qwen3 embedding and reranking models.
|
|
|
|
## When to use
|
|
|
|
- Concept questions: "where are expired trials blocked", "how is the cache invalidated", "which code retries failed uploads".
|
|
- Unfamiliar repositories where names and conventions are unknown.
|
|
- After an `rg` search for guessed terms returned nothing relevant or too many unrelated files.
|
|
|
|
Use `rg` or direct reads instead for known file paths, symbol names, exact strings, and error messages.
|
|
|
|
## Run
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
python "$HOME/.my-ai-configuration/semantic-retrieval/server.py" search --root . --data-dir "$HOME/.my-ai-configuration/semantic-retrieval/data" --model-cache "$HOME/.my-ai-configuration/semantic-retrieval/model-cache" --query "<question in natural language>" --top-k 5
|
|
```
|
|
|
|
Bash:
|
|
|
|
```bash
|
|
python3 "$HOME/.my-ai-configuration/semantic-retrieval/server.py" search --root . --data-dir "$HOME/.my-ai-configuration/semantic-retrieval/data" --model-cache "$HOME/.my-ai-configuration/semantic-retrieval/model-cache" --query "<question in natural language>" --top-k 5
|
|
```
|
|
|
|
The output is a JSON list of `{path, symbol, text, score}`, best match first.
|
|
|
|
## Use the results
|
|
|
|
1. Phrase the query as a full question about behavior, not as a keyword list.
|
|
2. Open the top hits and verify them against the current files before acting; the index can lag behind uncommitted edits by one refresh.
|
|
3. Follow the verified hit with `rg` for its symbols to find callers and tests.
|
|
|
|
## Cost and limits
|
|
|
|
- The first search in a repository builds its index, which can take minutes; later searches refresh only changed files.
|
|
- Outside a sandbox a background daemon keeps the models loaded, so warm searches take seconds. Inside the Codex sandbox every search loads the models again and takes about half a minute; batch related questions into one precise query.
|
|
- Only Git-tracked and unignored files up to 512 KB are indexed, by default at most 2000 files per repository.
|
|
- If the command fails or the setup is missing, continue with `rg` and state the limitation briefly.
|