giancarloerra/socraticode/codebase-exploration

Claude Code and agent skill by giancarloerra/socraticode

Trust tier 2
  • community
LLM review pending
Source check pending

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-exploration

SKILL.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 fileFilter to 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 languageFilter to narrow to one language, exactly as a result header shows its label in brackets (e.g. typescript, not ts)
  • 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=off plus SOCRATICODE_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; use codebase_update for 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

GoalTool
Understand what a codebase does / where a feature livescodebase_search (broad query)
Find a specific function, constant, or typecodebase_search (exact name) or grep
Find exact error messages, log strings, or regex patternsgrep / ripgrep
See what a file imports or what depends on itcodebase_graph_query
Get architecture overview (files, edges, most connected)codebase_graph_stats
Spot circular dependenciescodebase_graph_circular
Visualise module structure (text / Mermaid)codebase_graph_visualize
User asks for a visual / interactive / shareable graphcodebase_graph_visualize mode="interactive"
Check graph build statuscodebase_graph_status
Verify index is up to datecodebase_status
Discover available schemas, specs, configscodebase_context
Find database tables, API endpoints, infra configscodebase_context_search
Quick overview of all toolscodebase_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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/giancarloerra/socraticode/codebase-exploration/badge)](https://verified-skill.com/skills/giancarloerra/socraticode/codebase-exploration)

Something wrong with this skill or its page? Tell us.