veratools/vera/skill-v2

Vera

Ranked code search over an indexed repository. Results are markdown codeblocks: path:line_start-line_end symbol_type:symbol_name, then the code.

Pick the tool

Do not use Vera when

• You already know the exact path and line: open the file.
• You are editing across many files mechanically: use rg.
• The answer is a literal string you can match: vera grep beats vera search.
• You have already run two searches that returned the same region: stop searching and read the code.

Search well

• Search behavior, not nouns: "JWT expiry handling", not "auth" or "utils".
• Pass several angles in one call: vera search "OAuth token refresh" "JWT expiry" "auth middleware".
• Start broad with --compact (signatures only, fewer tokens), then narrow with --lang, --path, --type, --limit.
• Add --intent "<goal>" when the query is vague but the goal is clear.
• Scope to a change with --changed, --since <rev>, or --base <rev> when reviewing a diff.
• --deep rewrites the query through an LLM; use it only after normal search misses.

Treat hits as leads

• A search hit is a lead, not evidence. Before stating how something behaves, open the cited lines.
• Follow the call graph rather than re-searching: vera references <symbol> on a promising hit answers "who drives this" in one step.
• Cite path:line from code you actually read.
• After editing files, run vera update . before searching again.

Recovery

References

• references/install.md: install, setup, API and local config, .veraignore rules
• references/query-patterns.md: more query examples and rg guidance
• references/troubleshooting.md: common errors and fixes
• references/mcp.md: optional MCP server usage