Codebase Exploration
Developmentcodebase-explorationCodebase Exploration is an Agent Skill for development published in the repowise-dev/repowise repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when exploring, understanding, or answering questions about a codebase that has Repowise indexed (a .repowise/ directory in the project root). Activates for "how does X work", "explain the architecture", "where is Y implemented", "what does this module do", or any task that needs an understanding of structure before diving into source files.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/repowise-dev/repowise/blob/HEAD/plugins/claude-code/skills/codebase-exploration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/codebase-exploration, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Codebase Exploration with Repowise
This project has a Repowise intelligence layer. Before grepping and reading raw source to understand the codebase, reach for the Repowise MCP tools — they return documentation, ownership, history, decisions, and graph structure that plain file reads don't, usually in one round-trip instead of many.
Which tool for which question
| You want… | Call |
|---|---|
| First orientation in an unfamiliar repo | get_overview() — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |
| A direct answer to "how/where/why does X work" | get_answer(question="…") — synthesised answer with citations + a retrieval_quality signal. Collapses the search → read → reason loop. |
| Find a symbol, file, or fuzzy concept | search_codebase(query="…") — hybrid search. mode="auto" routes an identifier to indexed symbol hits (symbol_id/line bounds → pipe into get_symbol), a path to file pages (→ get_context), and prose to semantic wiki search (each hit reports search_method: embedding vs bm25). Force a branch with mode=symbol|path|concept|hybrid; narrow symbols with symbol_kind. |
| A triage card for specific files/symbols | get_context(targets=[…]) — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. |
| The actual source of one symbol | get_symbol("path/to/file.py::Name") — exact bytes with line bounds. Cheaper than Read + offset math. Use a symbol_id from get_context. |
Recommended flow
- New area you don't know →
get_overview()once. - A specific question →
get_answer(question=…)first.- High confidence → answer it, cite the paths.
medium/lowconfidence → followbest_guesses[0].fileorfallback_targets[0]intoget_context, thenget_symbolfor bytes.
- A named symbol or a path →
search_codebase(query="Name")/search_codebase(query="path/to/file.py"); symbol hits pipe straight intoget_symbol, file hits intoget_context. - More files around a concept →
search_codebase, thenget_contexton the hits (batched), thenget_symbolonly for the bodies you actually need.
Fall back to raw Read/Grep only when the indexed context doesn't cover the specific detail the user asked about.
Trust signals — verify when
_meta.stale_warningis present (the index has diverged from HEAD), orretrieval_qualityispartial/weak, or- a result's
search_methodisbm25.
Otherwise the response is current — act on it.
Error handling
- "No repositories found. Run 'repowise init' first." → suggest
/repowise:init. get_answer/search_codebasecome back empty → the repo may be in index-only mode (no wiki). Fall back toget_contextwith explicit paths, and note that full mode (/repowise:initwith an LLM provider) unlocks docs + semantic search.- Tools fail to connect at all → the
repowisebinary may not be installed; suggest/repowise:init.