giancarloerra/socraticode/codebase-exploration
Claude Code and agent skill by giancarloerra/socraticode
- community
Checking that the SKILL.md file is still in the repository.
Explore and understand codebases using SocratiCode semantic search, dependency graphs, and context artifacts. Use when exploring code, understanding architecture, finding functions/types, analysing dependencies, searching database schemas or API specs, or when socraticode/codebase_search tools are available. Activates when the user asks about code structure, wants to find where a feature lives, or needs to understand how code is organised.
Install
npx vskill@latest install giancarloerra/socraticode/codebase-explorationSKILL.md
The same SKILL.md was published earlier as giancarloerra/socraticode/codebase-exploration.
SocratiCode Codebase Exploration
Use SocratiCode MCP tools to explore codebases efficiently. The core principle: search before reading — the index gives you a map of the codebase in milliseconds; raw file reading is expensive and context-consuming.
Workflow
1. Start most explorations with codebase_search
Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
- Broad queries for orientation: "how is authentication handled", "database connection setup", "error handling patterns"
- Precise queries for symbol lookup: exact function names, constants, type names
- Prefer search results to infer which files to read — do not speculatively open files
- Use
fileFilterto narrow to one file, exactly as a result header shows its path; a directory, glob or bare name of a file below the root matches nothing - Use
languageFilterto narrow to one language, exactly as a result header shows its label in brackets (e.g.typescript, notts) - Adjust
minScore(default 0.10) for precision vs recall — lower for more results, higher for stricter matching
When to use grep instead: If you already know the exact identifier, error string, or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge. Use codebase_search when exploring, asking conceptual questions, or when you don't know which files to look in.
2. Follow the graph before following imports
Use codebase_graph_query to see what a file imports and what depends on it before diving into its contents. This prevents unnecessary reading of transitive dependencies.
- `codebase_graph_query` — imports and dependents for any file (pass relative path)
- `codebase_graph_stats` — architecture overview: total files, edges, most connected files, orphans, language breakdown
- `codebase_graph_circular` — find circular dependencies (these cause subtle runtime bugs; check proactively when debugging unexpected behaviour)
- `codebase_graph_visualize` — Mermaid diagram colour-coded by language, circular deps highlighted in red. Pass
mode: "interactive"to open a self-contained HTML explorer (file + symbol views, blast-radius overlay, search, PNG export — works offline) instead.
The graph is auto-built after indexing. Use codebase_graph_status to check if the graph is ready. In SOCRATICODE_WATCHER=manual or off, graph queries do not create a missing graph; run codebase_graph_build explicitly when requested.
3. Read files only after narrowing via search
Once search results clearly point to 1-3 files, read only the relevant sections. Never read a file just to find out if it's relevant — search first.
A single codebase_search call returns ranked, deduplicated snippets from across the entire codebase in milliseconds. This gives you a broad map at negligible token cost — far cheaper than opening files speculatively.
4. Leverage context artifacts for non-code knowledge
Projects can define a .socraticodecontextartifacts.json config to expose database schemas, API specs, infrastructure configs, architecture docs, and other project knowledge that lives outside source code.
- `codebase_context` — list available artifacts (names, descriptions, paths, index status)
- `codebase_context_search` — semantic search across all artifacts (or filter with
artifactName) - Artifacts are auto-indexed on first search and auto-detect staleness
Run codebase_context early to see what's available. Use codebase_context_search before asking about database structure, API contracts, or infrastructure.
5. Check status if something seems wrong
- `codebase_status` — check index status, progress, watcher state, graph status
- If search returns no results, the project may not be indexed yet
- If the watcher is inactive, results may be stale — run
codebase_update; start the watcher only when status does not say it is disabled - In snapshot mode (
SOCRATICODE_WATCHER=offplusSOCRATICODE_AUTO_RESUME=off), stale results are expected until an explicit update. Do not enable or start the watcher. - In Git mode (
SOCRATICODE_WATCHER=git), search, graph, and status requests report refresh state. Do not treat pending, failed, or unverified results as current. Git transitions trigger refreshes; usecodebase_updatefor an immediate refresh of working-tree edits. Do not start the file watcher.
6. Get an overview of all tools
- `codebase_about` — quick reference of all SocratiCode tools and a typical workflow
Goal → Tool Quick Reference
| Goal | Tool | |
|---|---|---|
| Understand what a codebase does / where a feature lives | codebase_search (broad query) | |
| Find a specific function, constant, or type | codebase_search (exact name) or grep | |
| Find exact error messages, log strings, or regex patterns | grep / ripgrep | |
| See what a file imports or what depends on it | codebase_graph_query | |
| Get architecture overview (files, edges, most connected) | codebase_graph_stats | |
| Spot circular dependencies | codebase_graph_circular | |
| Visualise module structure (text / Mermaid) | codebase_graph_visualize | |
| User asks for a visual / interactive / shareable graph | codebase_graph_visualize mode="interactive" | |
| Check graph build status | codebase_graph_status | |
| Verify index is up to date | codebase_status | |
| Discover available schemas, specs, configs | codebase_context | |
| Find database tables, API endpoints, infra configs | codebase_context_search | |
| Quick overview of all tools | codebase_about |
For full parameter details on every tool, see references/tool-reference.md.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/codebase-exploration/SKILL.md
Popularity
- Repository stars
- 3,335
- Repository forks
- 430
- Repository npm downloads, 7 days
- 2,918
- 7-day trend score
- 59
Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 21 May 2026, 6 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/giancarloerra/socraticode/codebase-exploration)