How do I install the Semantic Search skill?

Run npx skillmds@latest add tomevault-io/semantic-search in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Semantic Search safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Semantic Search?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Semantic Search free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Semantic Search?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Semantic Search by tomevault-io — Agent Skill

Name: Semantic Search
Author: tomevault-io

File contents

Hybrid Code Search (Beacon)

This repo has a Beacon hybrid search index combining semantic embeddings, BM25 keyword matching, and identifier boosting. Beacon is enforced as the default search — grep is automatically intercepted and redirected to Beacon for queries it handles better.

How to search

node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "<query>"

Options

--top-k N — number of results (default: 10)
--threshold F — minimum score cutoff (default: 0.35)
--no-hybrid — disable hybrid, use pure vector search only

Multi-query batch

node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "auth flow" "session handling" "token refresh"

Single HTTP round-trip for all queries. Returns grouped results.

Output

JSON array of matches, each with:

file — file path
lines — line range (e.g. "45-78")
similarity — vector cosine similarity
score — final hybrid score (when hybrid enabled)
preview — first 300 chars of matched chunk

Grep intercept behavior

Grep is denied and redirected to Beacon unless one of these conditions is met:

Grep passes through when...	Example
Pattern has regex metacharacters	`function\s+\w+`
Targets a specific file	`path: "src/lib/db.js"`
`output_mode` is `"count"`	Counting occurrences
Pattern is <= 3 characters	`fs`, `db`
Dotted identifier	`fs.readFileSync`, `path.join`
Path-like pattern (contains `/` or `\`)	`src/components`
`output_mode` is `"content"`	Viewing matching lines
Quoted string literal	`"use strict"`, `'Content-Type'`
Annotation/marker pattern	`TODO`, `FIXME`, `@param`, `#pragma`
URL-like pattern	`http://`, `localhost:3000`
Beacon index is unhealthy	DB missing, empty, dimension mismatch
Intercept disabled via config	`intercept.enabled: false`

To disable interception entirely, set intercept.enabled: false in .claude/beacon.json.

Workflow

Search with Beacon → get candidate files + line ranges with scores
Read top 2-3 files at the indicated line ranges for full context
If needed, grep within those files for specifics (imports, call sites)
Answer the user with file:line citations

Source: sagarmk/beacon-plugin — distributed by TomeVault.

---name: semantic-searchdescription: Primary code search — hybrid semantic + keyword + BM25 matching. Automatically intercepted as default search when Beacon index is healthy. Use when this capability is needed.---# Hybrid Code Search (Beacon)This repo has a Beacon hybrid search index combining semantic embeddings, BM25 keyword matching, and identifier boosting. **Beacon is enforced as the default search** — grep is automatically intercepted and redirected to Beacon for queries it handles better.## How to search```node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "<query>"```### Options- `--top-k N` — number of results (default: 10)- `--threshold F` — minimum score cutoff (default: 0.35)- `--no-hybrid` — disable hybrid, use pure vector search only### Multi-query batch```node ${CLAUDE_PLUGIN_ROOT}/scripts/search.js "auth flow" "session handling" "token refresh"```Single HTTP round-trip for all queries. Returns grouped results.### OutputJSON array of matches, each with:- `file` — file path- `lines` — line range (e.g. "45-78")- `similarity` — vector cosine similarity- `score` — final hybrid score (when hybrid enabled)- `preview` — first 300 chars of matched chunk## Grep intercept behaviorGrep is **denied and redirected** to Beacon unless one of these conditions is met:| Grep passes through when... | Example ||---|---|| Pattern has regex metacharacters | `function\s+\w+` || Targets a specific file | `path: "src/lib/db.js"` || `output_mode` is `"count"` | Counting occurrences || Pattern is <= 3 characters | `fs`, `db` || Dotted identifier | `fs.readFileSync`, `path.join` || Path-like pattern (contains `/` or `\`) | `src/components` || `output_mode` is `"content"` | Viewing matching lines || Quoted string literal | `"use strict"`, `'Content-Type'` || Annotation/marker pattern | `TODO`, `FIXME`, `@param`, `#pragma` || URL-like pattern | `http://`, `localhost:3000` || Beacon index is unhealthy | DB missing, empty, dimension mismatch || Intercept disabled via config | `intercept.enabled: false` |To disable interception entirely, set `intercept.enabled: false` in `.claude/beacon.json`.## Workflow1. Search with Beacon → get candidate files + line ranges with scores2. Read top 2-3 files at the indicated line ranges for full context3. If needed, grep **within those files** for specifics (imports, call sites)4. Answer the user with file:line citations---> Source: [sagarmk/beacon-plugin](https://github.com/sagarmk/beacon-plugin) — distributed by [TomeVault](https://tomevault.io).

Frequently asked questions

Semantic Search