code-health-check
npx machina-cli add skill huangjia2019/claude-code-engineering/code-health-check --openclawCode Health Check
Analyze the codebase at $ARGUMENTS and produce a structured health report.
Checks to Perform
1. File Organization
- Are files reasonably sized? (Flag files > 200 lines)
- Is the directory structure logical?
- Any files that look misplaced?
2. Error Handling
- Are async operations wrapped in try/catch?
- Are errors propagated correctly (not swallowed)?
- Is there a global error handler?
3. Security Basics
- Any hardcoded secrets, API keys, or passwords?
- Any use of
eval()or similar dangerous functions? - Are user inputs validated before use?
4. Code Quality
- Any obvious code duplication (similar blocks in multiple files)?
- Any unused variables or imports?
- Are function signatures reasonable (not too many parameters)?
5. Dependency Hygiene
- Are all imported modules actually used?
- Any circular dependencies?
Severity Levels
Use these to categorize issues:
| Severity | Meaning | Example |
|---|---|---|
| CRITICAL | Must fix immediately | Hardcoded secrets, SQL injection |
| WARNING | Should fix soon | Missing error handling, large files |
| INFO | Nice to improve | Minor duplication, naming conventions |
Output Format
Return a structured report in this exact format:
# Code Health Report: {directory}
## Overall Score: {A/B/C/D/F}
## Summary
- Files analyzed: {count}
- Issues found: {critical} critical, {warning} warnings, {info} info
## Critical Issues
{list each with file:line and description}
## Warnings
{list each with file:line and description}
## Info
{list each with file:line and description}
## Recommendations
{top 3 actionable recommendations}
Source
git clone https://github.com/huangjia2019/claude-code-engineering/blob/main/04-Skills/projects/07-skill-fork-demo/.claude/skills/code-health-check/SKILL.mdView on GitHub Overview
Analyzes a codebase at a given directory and surfaces health indicators across structure, error handling, security, quality, and dependencies. It outputs a structured health report with severity levels and concrete recommendations to guide fixes and improvements.
How This Skill Works
The skill examines the target directory (ARGUMENTS) using allowed tools to assess five areas: File Organization, Error Handling, Security Basics, Code Quality, and Dependency Hygiene. It then aggregates findings, assigns severity levels (CRITICAL, WARNING, INFO), and returns a Markdown-formatted Code Health Report following the specified Output Format.
When to Use It
- When you need a holistic health snapshot of a codebase to guide refactors
- Before a major release to catch structural or security issues
- When auditing a new or legacy project for maintainability and risk
- When you suspect error handling gaps or unused code and want evidence
- When reviewing dependency hygiene and potential circular dependencies
Quick Start
- Step 1: Provide the target directory path as ARGUMENTS
- Step 2: Run the code-health-check to generate a Code Health Report
- Step 3: Review the Markdown report and address high-severity findings
Best Practices
- Run the check on the full repository to avoid blind spots
- Prioritize CRITICAL and WARNING findings and validate fixes with tests
- Integrate regular checks into CI/CD or quarterly maintenance
- Exclude non-source directories if focusing strictly on code health
- Cross-check findings against your security and lint rules
Example Use Cases
- Audit a new repo to surface hardcoded secrets and unsafe eval usage
- Scan a legacy project to identify error handling gaps and large files
- Generate a health report before a major release to guide fixes
- Detect unused imports and duplication across modules
- Check for circular dependencies in a monorepo
