# Explain My Code > Explain My Code - Skill: `chrismccoy/explain-my-code` (Agent Skill) - Install (CLI): `npx skillmds@latest add chrismccoy/explain-my-code` - Raw SKILL.md: https://api.skillmd.com/api/skills/chrismccoy/explain-my-code/raw - Safety review: PASS (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: chrismccoy (https://skillmd.com/u/chrismccoy) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/chrismccoy/explain-my-code --- # Explain My Code Analyze a complete code repository as a senior software architect and produce one self-contained, production-grade Markdown document that lets anyone new to the project fully understand the system with no handover meetings or outside help. ## When to Use - User asks to document, explain, or map a codebase or repository - User wants an onboarding document for people new to the project - User wants a system/architecture overview with Mermaid diagrams - User points at a repo and asks "what does this do / how does it work" AND wants it captured as a written document, not a one-line reply Do NOT use for bug-finding code review, refactoring plans, or diagram-only output (see negative boundary in description). ## Co-Load Precedence When co-loading with codebase-to-mermaid: that skill owns standalone diagram generation; this skill embeds diagrams inside the full document. When co-loading with refactoring-analyst: that skill owns refactor planning; this skill only describes the system (Section 13 suggests improvements at a high level, it does not plan the refactor). When co-loading with a code-review skill (e.g. wordpress-architect-review): review owns defect findings; this skill owns architecture explanation (Section 12 lists observations/risks but does not perform line-level review). ## Workflow ### Phase 1: SCOPE THE TARGET 1. Determine the repository root. Default to the current working directory. If the user named a path, use that. 2. If no code is present at the target, STOP and ask the user for the repo path (see Error Handling). 3. Map the top-level layout with `Glob` (`**/*`) and read manifest/config files first (package.json, pom.xml, go.mod, requirements.txt, Cargo.toml, *.csproj, Dockerfile, compose files, CI configs). ### Phase 2: IDENTIFY FOUNDATIONS 1. Identify tech stack: languages, frameworks, frontend/backend/infra split, package managers. 2. Classify architecture: monolith vs microservices vs modular. 3. Locate entry points (main files, server bootstrap, CLI roots) and config loading. ### Phase 3: TRAVERSE SYSTEMATICALLY 1. Walk folder-by-folder, service-by-service, module-by-module. 2. Infer design patterns (MVC, Clean, Hexagonal, Factory, Observer, etc.) - record where and why each is used. 3. Trace core business logic, dependency flow, and data flow (input → processing → storage). 4. For large repos, analyze in chunks; accumulate knowledge and refine earlier sections as understanding improves (see Error Handling: large repo). ### Phase 4: WRITE THE DOCUMENT 1. Produce ALL 13 sections in the order under Output Format. Do not skip any section. 2. Use real file names, classes, and functions from the repo - never generic placeholders. 3. Embed Mermaid diagrams (`graph TD`, `sequenceDiagram`) where they clarify architecture and flow. 4. Where behavior is undocumented, infer logically and explicitly state the assumption. ### Phase 5: VERIFY BEFORE DELIVERY 1. Confirm every one of the 13 sections is present and non-shallow. 2. Confirm cited file/class/function names actually exist in the repo (`Grep`-verifiable - no invented symbols). 3. Confirm Mermaid blocks are syntactically valid. 4. Write the result to `CODEBASE_DOCUMENTATION.md` at the repo root (or a user-specified path) with `Write`, then tell the user the path. ## Output Format Single Markdown file, default name `CODEBASE_DOCUMENTATION.md`, containing these sections in order: 1. **Project Overview** - purpose, high-level functionality, key use cases 2. **System Architecture** - explanation, monolith/microservices/hybrid, Mermaid `graph TD` diagram 3. **Repository Structure** - folder hierarchy, role of each major directory, module responsibilities 4. **Tech Stack & Dependencies** - languages, frameworks, external libraries, package managers, dependency graph if possible 5. **Core Components / Services** - per component: responsibility, key classes/functions, interactions 6. **Application Flow** - 6.1 Startup flow (entry point, init sequence, config, DI); 6.2 Request/execution flow; 6.3 Auth flow if applicable; 6.4 Data flow; include Mermaid `sequenceDiagram` 7. **Key Design Patterns** - patterns used, where and why 8. **Database & Models** - schema overview, ORM usage, entity relationships 9. **External Integrations** - APIs, third-party services, queues, caches 10. **Configuration & Environment** - env vars, config files, build configs 11. **Build & Deployment** - build steps, scripts, CI/CD if present 12. **Observations & Risks** - code smells, tight coupling, scalability concerns, missing abstractions 13. **Suggestions for Improvement** - refactoring ideas, performance, architecture alternatives Constraints (from source prompt, preserved): - Be precise and technical; avoid generic explanations. - Do NOT give shallow summaries or skip flows/architecture. - Do NOT assume undocumented behavior without stating the reasoning. - The deliverable is the document file; keep it complete, structured, and self-sufficient for onboarding. ## Error Handling **No repository / empty target:** Ask the user for the repo path. Do not fabricate documentation for code that was not read. **Large repo (cannot read fully in one pass):** Tell the user, then analyze in chunks - manifests and entry points first, then per-module. Accumulate findings and refine earlier sections. Note any directories sampled rather than fully read. **Ambiguous path (multiple repos in directory):** Ask which repo to document before proceeding. **Generated/vendored code (node_modules, vendor, build, dist):** Exclude from traversal; mention it was skipped. **Section genuinely not applicable (e.g., no database):** Keep the heading, state "Not applicable - ". Do not silently drop a section. ## Quality Gates - [ ] All 13 sections present and substantive (no shallow summaries) - [ ] Cited file/class/function names verified to exist in the repo (accuracy gate) - [ ] At least one architecture diagram and one flow diagram in valid Mermaid syntax (format gate) - [ ] Assumptions about undocumented behavior are explicitly labeled - [ ] Output written to a `.md` file and its path reported to the user ## Examples **Standard case:** User runs the skill in a Node/Express + React repo. The skill reads package.json files, identifies a modular monolith, walks `server/` and `client/`, and writes `CODEBASE_DOCUMENTATION.md` with all 13 sections, a `graph TD` of the request path, and a `sequenceDiagram` of an authenticated API call - citing real route files and controllers. **Edge case:** User points at a directory containing two services and no top-level manifest. The skill detects ambiguity, asks which service to document (or confirms "both as one system"), excludes `node_modules`/`dist`, marks Section 8 "Not applicable - no database layer found", and states the assumption that inter-service calls are HTTP based on observed `fetch` usage.