codebase-audit
Audit and map a codebase to understand structure, dependencies, and risks. Use when the user asks to audit a repo, understand architecture, or assess codebase quality or health.
When & Why to Use This Skill
The Codebase Audit skill provides a comprehensive, automated solution for mapping and analyzing complex software repositories. By leveraging advanced diagnostic tools like Repomix, Tokei, and Ctags, it generates evidence-based insights into project structure, dependency hierarchies, and architectural risks. This skill is designed to help developers and architects quickly grasp system design, identify quality hotspots, and assess the overall health of a codebase through structured, data-driven reporting.
Use Cases
- Rapid Onboarding: Quickly understand the entry points, module boundaries, and folder structure when joining a new project or taking over a legacy repository.
- Technical Debt & Quality Assessment: Identify high-churn areas, unusually large files, and untested modules to prioritize refactoring efforts and improve maintainability.
- Security and Risk Mapping: Audit external dependencies, data flow paths, and environment assumptions to uncover potential security vulnerabilities or integration risks.
- Architecture Documentation: Automatically generate a detailed map of symbols, key flows, and module relationships to support system design reviews and technical documentation.
| name | codebase-audit |
|---|---|
| description | Audit and map a codebase to understand structure, dependencies, and risks. Use when the user asks to audit a repo, understand architecture, or assess codebase quality or health. |
Codebase Audit
Overview
Create a fast, evidence-based map of the repo and highlight risk and quality hotspots.
Inventory
- List top-level structure (use
ls,tree -L 3,rg --files). - Identify entry points (search for
main, CLI, or service starts). - Capture dependency manifests (pyproject, package.json, requirements, go.mod).
Required Tool Pass (must run all tools)
Run every tool below and log its output. If any tool is missing, invoke action-gate to install it and block the audit until the full tool pass is complete.
- Use OS-appropriate installers via action-gate (apt/dnf/yum/pacman/brew/choco/scoop) and retry.
rgfor search and inventory.tree -L 3for structure.tokei(orsccorcloc) for LOC; choose one and run it.ctagsor a tree-sitter indexer for symbol maps; choose one and run it.git log --statfor hotspots (if repo has history).repomapfor a scoped module summary (install if missing).repomixfor a full-repo map with ignores applied (install if missing).- Jina embeddings tooling for semantic clustering or duplication hints (install/configure if missing). If API key is required, stop and request it.
Repomap Scope Rules (required)
- Do not run repomap on the full repo if it times out; run it on scoped code folders (
scripts/,skills/, and other non-JS/JSX code dirs). - If repomap throws tree-sitter query errors for JS/JSX, skip those folders and rely on
ctagsfor symbol mapping. - If a target folder lacks
.gitignore, create a minimal.gitignorein that folder before running repomap.
Repomix Rules (required)
- Use repomix for the full-repo map and ensure
node_modules/and large data dirs are ignored. - Prefer a local
repomix.config.jsonor.repomixignoreif present; otherwise, generate one (repomix --init) and add ignore patterns. - Record the output file path and style used (markdown/json/plain).
Long-Run Handling
- If a tool is slow, use
timeoutor run undertmux/nohupto avoid session loss. Do not treat this as a fix for tool errors.
Risk and Quality Checks
- Large files, high churn areas, and untested modules.
- Security and PII paths, data flow, and external integrations.
- Configuration, environment assumptions, and hidden dependencies.
Output
- Module map, key flows, and hotspots.
- Findings with severity and suggested next steps.
- Open questions to confirm architecture or intent.
- Note which tools were run vs unavailable.
Acceptance Criteria
- Full tool pass completed with outputs captured.
- Any missing tool is reported and blocks the audit until resolved.
- Environment-specific install commands are documented when blockers occur.
- Repomap outputs are produced for scoped folders, and repomix output is produced for the full repo.