version: "1.0.0" name: codebase-search description: Task-specific local codebase-understanding workflow for OpenCode, MCP, Pi, omp, and Codex. Use compact context for unfamiliar repository orientation, direct definition and graph tools for known targets.

Codebase Search Skill

Use this skill when you need local repository knowledge before web lookup.

Core workflow

1. Run index_status when index readiness or freshness is unknown.
2. When repository orientation is needed (layout, relevant symbols, or cross-file intent), use one compact codebase_context(query, tokenBudget: 600, limit: 5) first pass and inspect returned evidence before broad reads or searches. Do not call it mechanically before every task or tool.
3. For a known definition, use implementation_lookup(query) directly. For callers or callees, use call_graph(name, direction) directly; for relationships between identified endpoints, use call_graph_path(from, to) directly.
4. For a change with a known or suspected target symbol, optionally use codebase_edit_context for bounded target source plus direct callers and callees.
5. Use codebase_peek(query, ...) when only semantic locations are needed, and codebase_search(query, ...) when matching source content is needed. Neither requires another context call when the task is already scoped.
6. Read known paths directly and use grep for exact identifiers or exhaustive literal matches. Use find_similar(code) for analogous implementations and duplicates.

Avoid repeating broad reads or retrieval when existing evidence already answers the question. If results are weak, check readiness, compatibility, and scope with index_status; run index_codebase only when the index is missing, stale, or incompatible.

Tool Priority

• codebase_context for compact, unfamiliar-repository orientation; explicit symbol and from + to routing remains supported.
• implementation_lookup for known definitions.
• call_graph and call_graph_path for relationships once symbols or endpoints are identified.
• codebase_edit_context as an optional bounded pre-edit step.
• codebase_peek for metadata-only semantic locations.
• codebase_search for matching implementation content.
• find_similar for pattern matching and duplication.
• index_codebase (force/estimate/dryRun/verbose) for first-time or stale indexes.
• index_status, index_health_check, index_metrics, index_logs for operational checks.

Suggested Commands

• Unfamiliar subsystem: codebase_context("payment processing flow", tokenBudget: 600, limit: 5).
• Known definition: implementation_lookup("validate").
• Callers or callees: call_graph("chargeCard", "callees").
• Known endpoints: call_graph_path("submitPayment", "chargeCard").
• Change target: codebase_edit_context(query: "reject expired tokens", symbol: "validateToken").
• Matching source after scope is known: codebase_search("payment retry guards").
• Analogous code: find_similar("function validate(data)").

Additional Notes

• Use grep for exact identifiers and tiny, deterministic lookups.
• Use websearch only when local tools return no results and docs are likely missing.
• Choose the next tool from the evidence needed, not a mandatory context → peek → search chain.