# Code Explainer

> Analyze a local codebase folder or GitHub repository URL and generate a grounded onboarding explainer with clear markdown docs, focused Mermaid/SVG/PNG diagrams, evidence anchors, and explanation-quality scoring. Use when users need a codebase explained in simple, concrete language for PM/design/new engineer onboarding.

- Skill: `baboonzero/code-explainer` (Agent Skill, multi-file: 54 files)
- Install (CLI): `npx skillmds@latest add baboonzero/code-explainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baboonzero/code-explainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: baboonzero (https://skillmd.com/u/baboonzero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/baboonzero/code-explainer

---


# Code Explainer

Builds explanation-first repository explainers from local folders or GitHub URLs.

## What Good Output Looks Like

A good run must do all of the following:

1. Explain what the repository does in plain language.
2. Name real entrypoints, modules, docs, and flow steps from the repository.
3. Tell the reader where to start and where change risk lives.
4. Produce diagrams that answer specific onboarding questions.
5. Emit proof artifacts showing whether the explanation is actually useful.

This skill should fail quality gates if the output is generic, vague, or weakly grounded.

## Output Model

1. `overview/OVERVIEW.md` for the plain-language explanation.
2. `deep/*.md` for architecture, modules, flows, dependencies, and glossary.
3. `diagrams/*.mmd` plus rendered `diagrams/svg/*.svg` and `diagrams/png/*.png`.
4. `diagrams/excalidraw/*.excalidraw.json` plus mirrored preview assets under `diagrams/excalidraw/svg/*.svg` and `diagrams/excalidraw/png/*.png`.
5. `meta/explanation_plan.json` describing the intended narrative.
6. `meta/explanation_quality.json` scoring clarity, specificity, grounding, usefulness, diagram usefulness, and honesty.
7. `meta/excalidraw_report.json` proving whether editable Excalidraw scenes were created or why that export was blocked.
8. `meta/*.json` for indexing, verification, confidence, attribution, and quality reports.

See `references/output-contract.md` for exact artifacts and `references/evaluation-rubric.md` for the passing bar.

## Command

Run from this skill directory:

```bash
python scripts/analyze.py analyze \
  --source <local_path_or_github_url> \
  --output <output_dir> \
  --mode <quick|standard|deep> \
  --format <markdown|html|both> \
  --explainer-type <onboarding|project-recap|plan-review|diff-review> \
  --audience <nontech|mixed|engineering> \
  --overview-length <short|medium|long> \
  --since <time_window> \
  --git-ref <ref> \
  --plan-file <path> \
  --include-glob <pattern> \
  --exclude-glob <pattern> \
  --enable-llm-descriptions <true|false> \
  --enable-excalidraw-export <true|false> \
  --enable-official-excalidraw-bridge <true|false> \
  --ask-before-llm-use <true|false> \
  --prompt-for-llm-key <true|false> \
  --persist-llm-key <ask|true|false> \
  --enable-web-enrichment <true|false>
```

Defaults:

- `mode=standard`
- `format=markdown`
- `explainer-type=onboarding`
- `audience=nontech`
- `overview-length=medium`
- `enable-llm-descriptions=true`
- `enable-excalidraw-export=true`
- `enable-official-excalidraw-bridge=false`
- `ask-before-llm-use=false`
- `prompt-for-llm-key=true`
- `persist-llm-key=ask`
- `enable-web-enrichment=true`

## LLM Behavior

- The high-quality path is explanation-first and uses `scripts/llm_describe.py`.
- The LLM path is the required production path for this skill.
- If `CODE_EXPLAINER_LLM_API_KEY` or `OPENAI_API_KEY` is set, the skill can use a live model.
- If no key is available, the skill should prompt for one when the terminal is interactive.
- The user can choose to persist the provided key in a local `.env` file for future runs.
- `CODE_EXPLAINER_MOCK_LLM=true` is only for explicit development or offline test scenarios and is not the normal production path.

## Workflow

1. Normalize the source and build a repository index.
2. Detect stack, entrypoints, dependencies, flows, and documentation coverage.
3. Build `explanation_plan.json` with top modules, audience starting points, diagram purposes, and caveats.
4. Generate the narrative layer with LLM or grounded mock/deterministic fallback.
5. Build focused diagrams tied to onboarding questions.
6. Export those diagrams into editable Excalidraw scenes through the deterministic local exporter.
7. Optionally prefer the official Excalidraw bridge only when explicitly enabled for development experiments.
8. Generate overview and deep docs from the explanation plan plus narrative layer.
9. Run fact-check and explanation-quality evaluation.
10. Fail the run if quality gates do not clear the rubric.

## Proof Path

Run the shipped self-audit:

```bash
python scripts/self_audit.py
```

This runs the skill on fixture repositories in `assets/fixtures/`, uses the grounded mock explainer path, and writes proof artifacts under `.audit_tmp/code-explainer-self/`.

## Dependencies

Required:

- Python `3.10+`
- Node.js `18+` + npm
- Git when `--source` is a GitHub URL

Recommended:

- Mermaid CLI (`mmdc`) from `@mermaid-js/mermaid-cli` for higher-fidelity diagram rendering
- Node.js is only required for GitHub cloning and optional development-time Excalidraw bridge experiments

Install dependencies:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install_runtime.ps1
```

or

```bash
bash ./scripts/install_runtime.sh
```

## Notes

- This skill does not mutate the analyzed repository.
- The skill may create or update a local `.env` file in the skill directory when the user chooses to persist the prompted LLM key.
- If the explanation-quality score is below the rubric threshold, treat the output as failed even if files were produced.
- If Excalidraw export is enabled, treat missing or partial editable scene generation as a real quality issue, not a cosmetic extra.
- The deterministic local Excalidraw exporter is the canonical production path.
- The official `@excalidraw/mermaid-to-excalidraw` bridge is opt-in only via `--enable-official-excalidraw-bridge true` and should be treated as a development experiment, not a required runtime dependency.
- Use include/exclude globs to narrow analysis when the repository is very large or noisy.

## References

- `references/output-contract.md`
- `references/diagram-style-guide.md`
- `references/persona-writing-guide.md`
- `references/mode-behavior.md`
- `references/evaluation-rubric.md`