# Code Health Check > Run a comprehensive codebase health analysis covering dead code, dependency freshness, test coverage gaps, security surface, and complexity hotspots. Produces a scored report with prioritized remediation. Use when the user asks to "check health", "audit the codebase", "code quality", or "technical debt". - Skill: `myclaude-sh/code-health-check` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add myclaude-sh/code-health-check` - Raw SKILL.md: https://api.skillmd.com/api/skills/myclaude-sh/code-health-check/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: myclaude-sh (https://skillmd.com/u/myclaude-sh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/myclaude-sh/code-health-check --- # Code Health Check > Automated codebase health analysis with scored report and prioritized fixes. **When to use:** Before a release, during sprint planning, onboarding to a new codebase, or anytime you need a structured quality snapshot. **When NOT to use:** For runtime debugging (use a debugger). For security-specific audits (use a dedicated security tool). This is a structural health check, not a pentest. --- ## Activation Protocol Before running any checks: 1. **Load check definitions:** Read `references/health-checks.md` 2. **Load scoring:** Read `references/scoring-methodology.md` 3. **Detect project type:** Glob for package.json, pyproject.toml, Cargo.toml, go.mod 4. **Scope the check:** - If `$ARGUMENTS` provided, use as path scope - If not, use current working directory 5. **Verify it's a code repo:** Check for `.git/` or source files - If no code found: "This doesn't appear to be a codebase. Point me to a project directory." --- ## Question System | Input | Required | If Missing | |-------|----------|-----------| | Target path | Yes | Ask: "Which directory should I analyze?" | | Depth | No | Default: full (all 5 dimensions) | | Exclusions | No | Default: node_modules, .git, dist, build, vendor | --- ## Core Instructions Run 5 health dimensions in sequence. Each produces a 0-100 score. ### Dimension 1: Dead Code (weight: 15%) ```bash # Find unused exports grep -r "export " --include="*.ts" --include="*.js" | # extract export names # Cross-reference with imports across codebase # Unused export = dead code candidate ``` - Glob all source files - Extract exported symbols (functions, classes, constants) - Grep for imports/usage of each symbol - Score: 100 - (dead_exports / total_exports × 100) ### Dimension 2: Dependency Health (weight: 20%) - Read package.json / requirements.txt / Cargo.toml - Check last publish date of each dependency (if available via Bash) - Flag: dependencies > 1 year old, deprecated packages, known CVEs - Score: 100 - (stale_deps / total_deps × 100) ### Dimension 3: Test Coverage (weight: 25%) - Glob test files (*.test.*, *.spec.*, test_*, *_test.*) - Glob source files - Calculate ratio: test_files / source_files - Check for test configuration (jest.config, pytest.ini, etc.) - Score: (test_ratio × 50) + (has_config × 25) + (has_ci × 25) ### Dimension 4: Security Surface (weight: 20%) - Grep for hardcoded secrets (API keys, tokens, passwords) - Check for eval(), exec(), dangerouslySetInnerHTML - Check .env.example exists (if .env is gitignored) - Check dependency audit (npm audit / pip-audit) - Score: 100 - (findings × 10), min 0 ### Dimension 5: Complexity Hotspots (weight: 20%) - Find files > 500 lines (candidates for splitting) - Find functions > 50 lines (candidates for extraction) - Find deeply nested code (> 4 levels of indentation) - Score: 100 - (hotspots / total_files × 100) --- ## Quality Gate Before presenting the report, verify: - [ ] All 5 dimensions produced a numeric score (0-100) - [ ] At least 10 files were analyzed (otherwise scope is too narrow) - [ ] Each finding has a specific file path (not generic advice) - [ ] Remediation priorities are ordered by impact (not alphabetically) --- ## Pre-Execution Gate Before running checks: - [ ] Target directory exists and contains source files - [ ] At least one recognized language detected - [ ] Not running inside node_modules or .git - [ ] Sufficient context to complete analysis --- ## Degradation Handling | Missing Element | Behavior | |----------------|----------| | No tests at all | Score dimension 3 at 0, note "No test infrastructure detected" | | No package manager | Skip dimension 2, note "No dependency manifest found" | | Binary/generated files | Exclude from analysis, note count | | Monorepo | Ask which package to analyze, or run on root | | Empty directories | Skip, don't count as dead code | --- ## Anti-Patterns 1. **Counting lines as quality** — More lines ≠ worse. Measure complexity, not volume. 2. **Flagging all old dependencies** — Stable deps (lodash, express) being "old" is fine. 3. **Test file ratio as coverage** — File existence ≠ meaningful test coverage. 4. **Generic advice** — "You should write more tests" is useless. Specify WHICH files need tests. 5. **Ignoring context** — A prototype has different health standards than production code. 6. **Running on vendor code** — Always exclude node_modules, vendor, generated code. 7. **One-time snapshot thinking** — Health checks should be re-run periodically, not once. --- ## Output Format ``` CODE HEALTH REPORT — {project_name} Generated: {date} | Scope: {path} | Files: {N} OVERALL HEALTH: {score}/100 {grade} Dead Code {score}/100 ████████░░ {dead_count} unused exports Dependencies {score}/100 ██████████ {stale_count} stale, {vuln_count} vulnerable Test Coverage {score}/100 ██████░░░░ {test_ratio}% file coverage Security Surface {score}/100 █████████░ {finding_count} findings Complexity {score}/100 ████████░░ {hotspot_count} hotspots TOP PRIORITIES (fix these first): 1. {file:line} — {issue} — {impact} 2. {file:line} — {issue} — {impact} 3. {file:line} — {issue} — {impact} DETAILED FINDINGS: {N} total across 5 dimensions [See below for per-dimension breakdown] ``` Grade scale: A (90+), B (75-89), C (60-74), D (40-59), F (<40)