explain-codebase

explain-codebase-skill

A Claude Code skill that explains how a codebase works through ASCII diagrams and clear prose — and uses codegraph for fast structural exploration when it's available.

Ask "how does authentication work?", "walk me through the request flow", or "give me an overview", and Claude answers with a monospace diagram (flow, tree, sequence, layers, state machine) plus cited file:line references and concrete follow-up questions.

What it does

• Diagram-first explanations. Anything with structure, flow, or state gets an ASCII diagram, not just paragraphs.
• codegraph-accelerated exploration (optional). When codegraph is installed and the project is indexed, the skill queries the pre-built code graph (query, callers, callees, impact) instead of repeatedly grepping and reading — typically cutting exploration tokens and tool calls by roughly half. If codegraph isn't present, it falls back to the usual Glob/Grep/Read.
• Honest about staleness. Graph output and doc claims are treated as leads to verify against the current source, never as ground truth.

Install

As a plugin (recommended)

/plugin marketplace add doyled-it/explain-codebase-skill
/plugin install explain-codebase@doyled-it-skills

As a bare skill

Clone and symlink the skill directory into your skills folder:

git clone https://github.com/doyled-it/explain-codebase-skill.git
ln -s "$PWD/explain-codebase-skill/plugins/explain-codebase/skills/explain-codebase" ~/.claude/skills/explain-codebase

Optional: codegraph

The skill works without it, but installs cheaply and pays for itself on any repo you explore more than once:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
cd your-project && codegraph init && codegraph index

See plugins/explain-codebase/skills/explain-codebase/references/codegraph.md for the full command reference and MCP-server setup.

Layout

.claude-plugin/
  marketplace.json                 # marketplace, plugin source "./plugins/explain-codebase"
plugins/explain-codebase/
  .claude-plugin/plugin.json       # plugin manifest
  skills/explain-codebase/
    SKILL.md                       # behavior, exploration strategy, gotchas
    references/
      diagram-toolkit.md           # ASCII pattern gallery + worked examples
      codegraph.md                 # install, commands, MCP setup

Works in both Claude Code and Codex (codex plugin marketplace add doyled-it/explain-codebase-skill → codex plugin add explain-codebase@doyled-it-skills).

License

MIT — see LICENSE.